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IBM Program License Agreement 


YOU SHOULD CAREFULLY READ THE FOLLOWING TERMS AND 
CONDITIONS BEFORE OPENING THIS DISKETTE(S) OR CASSETTE(S) 
PACKAGE. OPENING THIS DISKETTE(S) OR CASSETTE(S) PACKAGE 
INDICATES YOUR ACCEPTANCE OF THESE TERMS AND CONDITIONS. 
IF YOU DO NOT AGREE WITH THEM, YOU SHOULD PROMPTLY 
RETURN THE PACKAGE UNOPENED; AND YOUR MONEY WILL BE 


REFUNDED. 


IBM provides this program and licenses 
its use in the United States and Puerto 
Rico. You assume responsibility for the 
selection of the program to achieve your 
intended results, and for the installation, 
use and results obtained from the 
program. 


LICENSE 
You may: 
a. use the program on a single machine; 


b. | copy the program into any machine 
readable or printed form for backup 
or modification purposes in support 
of your use of the program on the 
single machine (Certain programs, 
however, may include mechanisms to 
limit or inhibit copying. They are 
marked “‘copy protected.’’); 


ec: modify the program and/or merge it 
into another program for your use on 
the single machine (Any portion of 
this program merged into another 
program will continue to be subject to 
the terms and conditions of this 
Agreement.); and, 


d. _ transfer the program and license to 
another party if the other party agrees 
to accept the terms and conditions of 
this Agreement. If you transfer the 
program, you must at the same time 
either transfer all copies whether in 
printed or machine-readable form to 
the same party or destroy any 
copies not transferred; this includes 
all modifications and portions of the 
program contained or merged into 
other programs. 


You must reproduce and include the 
copyright notice on any copy, 
modification or portion merged into 
another program. 


YOU MAY NOT USE, COPY, 
MODIFY, OR TRANSFER THE 
PROGRAM, OR ANY COPY, 
MODIFICATION OR MERGED 
PORTION, IN WHOLE OR IN PART, 
EXCEPT AS EXPRESSLY PROVIDED 
FOR IN THIS LICENSE. 


IF YOU TRANSFER POSSESSION OF 
ANY COPY, MODIFICATION OR 
MERGED PORTION OF THE 
PROGRAM TO ANOTHER PARTY, 
YOUR LICENSE IS AUTOMATICALLY 
TERMINATED. 


TERM 


The license is effective until terminated. 
You may terminate it at any other time 
by destroying the program together with 
all copies, modifications and merged 
portions in any form. It will also 
terminate upon conditions set forth 
elsewhere in this Agreement or if you 
fail to comply with any term or condition 
of this Agreement. You agree upon such 
termination to destroy the program 
together with all copies, modifications 
and merged portions in any form. 


LIMITED WARRANTY 


THE PROGRAM IS PROVIDED “AS 
IS” WITHOUT WARRANTY OF ANY 
KIND, EITHER EXPRESSED OR 
IMPLIED, INCLUDING, BUT NOT 
LIMITED TO THE IMPLIED 
WARRANTIES OF 
MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE. THE 
ENTIRE RISK AS TO THE QUALITY 
AND PERFORMANCE OF THE 
PROGRAM IS WITH YOU. SHOULD 
THE PROGRAM PROVE DEFECTIVE, 
YOU (AND NOT IBM OR AN 
AUTHORIZED PERSONAL 
COMPUTER DEALER) ASSUME THE 
ENTIRE COST OF ALL NECESSARY 
SERVICING, REPAIR OR 
CORRECTION. 
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The following paragraph does not apply to the United Kingdom or any country where such 

provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES 
CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY 

OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT 

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR 

FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of 

express or implied warranties in certain transactions, therefore, this statement may not 

apply to you. (‘> 


This publication could include technical inaccuracies or typographical errors. Changes are 
periodically made to the information herein; these changes will be incorporated in new 
editions of the publication. IBM may make improvements and/or changes in the 
product(s) and/or the program(s) described in this publication at any time. 


It is possible that this publication may contain reference to, or information about, IBM 

products (machines and programs), programming, or services that are not announced in 
your country. Such references or information must not be construed to mean that IBM 
intends to announce such IBM products, programming, or services in your country. 


Products are not stocked at the address below. Requests for copies of this publication and 
for technical information about IBM Personal Computer products should be made to your 
authorized IBM Personal Computer dealer, IBM Product Center, or your IBM Marketing 

Representative. 


The following paragraph applies only to the United States and Puerto Rico: A Reader’s 
Comment Form is provided at the back of this publication. If the form has been removed, 
address comments to: IBM Corporation, Personal Computer, P.O. Box 1328-C, Boca 
Raton, Florida 33432. IBM may use or distribute any of the information you supply in 
any way it believes appropriate without incurring any obligations whatever. 


© Copyright International Business Machines Corporation 1985 “& 
Microsoft® is a registered trademark of Microsoft Corporation. : 


How to Use This Product 


This book is volume one of a two-volume set. The IBM 
Personal Computer BASIC Compiler Version 2.00 uses 
IBM BASIC and the IBM BASIC Compiler. 


\& Throughout this book, the phrase JBM BASIC refers to 
the BASIC language that has been developed 
specifically for the IBM Personal Computer. 


You should have a working knowledge of BASIC 
programming concepts before using this product 
because this book does not teach the BASIC language. 
Our purpose is to teach you how to use the IBM BASIC 
Compiler. 


The IBM BASIC Compiler Version 2.00 is made up of 
four parts: 


¢ BASIC Compiler 2.00 Fundamentals 

¢ BASIC Compiler 2.00 Language Reference 

© BASIC Compiler 2.00 Quick Reference 

- Compiler Software Diskettes. 

The BASIC Compiler Fundamentals describes how to 
use the compiler to test, debug, and run BASIC 


programs. This book is designed to be read from front 
to back. 


The BASIC Compiler Language Reference contains 

information on the specific statements and commands 
(keywords) that are used in writing programs. This 

book is designed as a reference tool. The keywords and 
commands are alphabetized and can be looked up in the 

table of contents, or in the index. The BASIC Compiler 

2.00 Quick Reference also provides an easy-access 

reference of all statements and functions. (y 


The Compiler diskettes, two in all, contain the software 
to compile and run your programs. 


Compiled programs can be debugged using the BASIC 
Interpreter. 


Most IBM BASIC programs compile and run on the 
IBM Personal Computer. Because IBM BASIC 
Compiler Version 2.00 introduces new reserved words 
and other elements, however, some BASIC programs 
may require changes to compile and/or run on other 
systems. 


About this Book - 


This book explains how to use the IBM BASIC 
Compiler and general concepts about the compiler. 
The front part of the book has step-by-step procedures 
for setting up and using the compiler. A sample 
program is included to guide the new user through the 
entire process, from compiling to running. 


The remainder of the book explains BASIC Compiler 
general concepts. Specifics about BASIC Compiler 
statements, functions, and commands are in the JBM 
BASIC Compiler Language Reference book. The 
following describes the chapters and appendixes. 


¢ Chapter 1, ‘“‘Introducing the BASIC Compiler 
2.00,” introduces the BASIC Compiler and defines 
common terms. “ 
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Chapter 2, ‘““Setting Up Your Compiler — The 
First Time Through,” guides you step-by-step 
through the first time the compiler is used. 


Note: For experienced programmers — If you 
have complete BASIC programs that are ready 
to be compiled and run, this chapter gets you 
Started right away. If you need to create 
BASIC programs, be sure to read Chapter 1 
and Chapters 5 through 8. 


Chapter 3, “Sample Session: Compile, Link, and 
Run,” takes you step-by-step through the entire 
process using a sample program supplied with the 
compiler. 


Chapter 4, ““Compiling BASIC Programs,” explains 
in detail the operation of the compiler, and the 
compiler parameters. 


Chapter 5, ‘““Building a BASIC Source Program,” 
gives general information about programming in 
BASIC. 


Chapter 6, “Input and Output (1/O),” explains 
how files and devices are handled in BASIC. 


Chapter 7, “‘Data Types,”’ describes the forms of 
data that are recognized by BASIC. 


Chapter 8, ““Numeric and String Expressions,”’ 
explains the arithmetic, logical, and relational 
operators, and how they can be used with strings 
and numbers to perform useful functions. 


Appendix A, ‘““Memory Information,”’ contains 
memory maps and other memory-related 
information. 


Appendix B, ‘““Communications,” gives information 
necessary to establish communications input and 
output. 


e Appendix C, ‘““Modular Programming,” explains the 
techniques for building a program from separate 
modules. 
e Appendix D, “Using IBM Personal Computer 
ISAM Files,” gives detailed information on the use 
of an indexed sequential access method. a, 
e Appendix E, “Using the Library Manager,” 


explains how to create and maintain a library of 
independent modules. 


Hardware Requirements 


The hardware necessary to use this product is: 

e Any of the following IBM Personal Computers: 
— IBM Personal Computer 
— IBM Personal Computer XT 


— IBM Personal Computer AT “a 


— IBM Portable Personal Computer 
— IBM PCryr. 


¢« Aminimum of 128K bytes of Random Access 
Memory (RAM). 


Note: Additional memory can significantly 
improve the performance of the BASIC 
Compiler 2.00 and the Linker when used on 
all of the above listed computers. 


e One or two diskette drives, or a fixed disk: 
Double-sided diskette drives are required. 


e A printer (highly recommended). & 
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« Adisplay screen. Any of the following are 
suitable: 


— IBM Personal Computer Monochrome 
Display 


— IBM Personal Computer Color Display 


— IBM Personal Computer Enhanced Color 
Monitor 


— IBM Personal Computer Professional Color 
Monitor 


— An RGB monitor 
— A composite color monitor 
— A television set with an RF ac pter. 
Note: IBM supplies RF adapters for the 
IBM PCjr only. RF adapters for the IBM 
Personal Computer must be obtained 
yy from a source outside of IBM. 
Although any of the above displays can be 
used, best results are obtained with a display 


that can display 80 columns of information. 


2 Blank, formatted diskettes. 


Related Products 


The following books provide information that may be 
helpful when using BASIC Compiler 2.00. 


e IBM Personal Computer Disk Operating System 


e IBM Personal Computer Disk Operating System ‘y 
User’s Guide 


e IBM Personal Computer Disk Operating System 
Technical Reference. 


The following books contain additional, detailed 
information: 


. IBM Personal Computer BAS/JC (Interpreter) 
e IBM Personal Computer Guide to Operations 


e IBM Personal Computer Technical Reference 


° IBM PCjr BASIC (Interpreter) 


e IBM PCjr Hands-On BASIC for the IBM PCjr 
e IBM PCjr Guide to Operations 


e IBM PCjr Technical Reference. 
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Summary of Changes 


Changes in BASIC Compiler 2.00 


BASIC Compiler 2.00 differs from BASIC Compiler 
1.00 in the following areas: 


Improved program control structures allow a more 
modular approach to programming. Enhancements 
include: ) 


— Named subprograms 

— Named COMMON blocks 

— User-defined multiline functions 

— Separately compiled BASIC subprograms 
— Ability to branch to alphanumeric labels. 


Larger programs can be compiled. The use of a 
memory model that separates the instruction space 
from the data space allows this, as well as allowing 
more than twice as much symbol table space. 
Please note, however, that the data segment has a 
maximum upper limit of 64K bytes. In addition, 
allocated string space is also limited to a maximum 
of 64K bytes. 


Large dynamic arrays are supported. The 
maximum index for any dimension of a numeric 
array is 32766. This dimension limit and the 
amount of memory in your machine are the only 
size restrictions for numeric arrays. 
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.EXE files produced by BASIC Compiler 2.00 are 
larger than those produced by BASIC Compiler 
Version 1.00. 

Graphics capabilities are expanded. All graphics 
features of the BASIC Interpreter are available. 
These include the following statements: 

—- VIEW 

—- WINDOW 

— PMAP 

—- LINE 

—- DRAW 

— POINT 

— PAINT. 

Access to DOS is expanded. Several new features 
of the BASIC Interpreter are available to allow 
more flexible use of DOS functions. Statements 
affected are: 

—- SHELL 

—- [0CTL 

—- IOCTL$ 

— ENVIRON 

—- ENVIRON$ 

—  ERDEV 

—  ERDEV$ 


—-  MKDIR 


—-  RMDIR 
—  CHDIR. 


The filespec syntax is expanded to allow the 
specification of a path for a device or file. 


Redirection of standard input and standard output 
is supported. 


Enhanced event trapping is available. This 
enhancement affects the following statements: 


— ON TIMER 

— ON PLAY 

— ON KEY. 

All advanced features of PCjr BASIC are 
supported. The full range of sound and graphics 
capabilities are available to users of PCjr Some of 


the features include: 


PLAY — Multi-voice 


— PLAY — Volume Control 

—- NOISE 

— Enhanced SCREEN statement 

— Enhanced CLEAR statement 

— PCOPY 

— User-defined PALETTE 

— Additional screen modes. 

Compiler termination codes are returned when the 


compiler exits. These termination codes can be 
tested by the IF batch subcommand of DOS. 
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e An input editor is included. Input required by your 
program can be easily altered on the screen. 


e Support is provided for up to five levels of nested 
$INCLUDE files. 


e When compiling, you must specify the /D ‘> 
parameter to Ctrl-Break effectively at runtime. 


« BASIC library files are searched in the following 
order: 


1. User-specified directory 
2. Current directory 

3. PATH directories 

4. User-prompted directory. 


e Graphics statements now use line clipping instead 
of wraparound. 


. The OPEN statement has been enhanced to “a 
include file access control. 


« Because of the added functions in BASIC 
Compiler 2.00, you may notice slighter longer 
compile and link times. 


BASIC Compiler Version 2.00 includes the following 
language additions: 


Metacommands 


$DYNAMIC 
Causes space for arrays to be dynamically 
allocated. 


S$MODULE “ 


Changes the name of the internal module 
that is passed to the Linker. 
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SSTATIC 


Statements 
CALLS 


Causes space for arrays to be statically 
allocated. 


Calls and transfers program control to IBM 
Personal Computer Macro Assembler 
routines. 


DEF FN, END DEF, EXIT DEF 


Designate the beginning and ending of a 
multiline function. 


LOCK, UNLOCK 


REDIM 


SHARED 


STATIC 


Restricts access by other processes to all or 
part of an opened file. 


Changes the space allocated to a dynamic 
array. 


Designates variables as global to the 
subprogram and the calling program. 


Designates variables as local to a 
subprogram or multiline function. 


SUB, END SUB, EXIT SUB 


Functions 


Designate the beginning and ending of a 
subprogram. 


COMMANDS 


LBOUND 


Returns the parameters from the command 
line used to invoke the current program. 


Returns the value of the lowest subscript 
available (either O or 1) for any array. This 
value depends on the setting of the 
OPTION BASE statement. 


UBOUND Returns the value of the largest subscript 
available for any array. 


New File Type 


ISAM ‘ty 


BASIC Compiler 2.00 now supports the indexed 
sequential access method. These ISAM files are 
accessed through the CALL statement. ISAM files 
allow for rapid access to large files by key values. 

Other features are automatic storage space management 
and fast sequential access. See Appendix D, “‘Using 
IBM Personal Computer ISAM Files,”’ for details. 


Library Manager 


The IBM Library Manager is included. This utility 
enables you to construct and edit object module 
libraries. See Appendix E, ‘“‘Using the Library 
Manager,” and ‘“‘Creating A Library of Modules”’ in 
Appendix C for details. 


Publication Changes 


The books included with BASIC Compiler 2.00 are 
newly designed and written. We have divided the 
publication into two books for easy access to 
fundamental information and reference information. 
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Introduction 


This chapter defines common terms and describes the 
BASIC Compiler. Additional terms are defined in the 
glossary. 


What is a Compiler? 


A computer can perform only its own machine 
instructions; it does not perform BASIC statements 
directly. Therefore, before a program can be run, some 
type of translation must occur from the statements in 
your BASIC program to the machine language of your 
computer. Interpreters and compilers are two types of 
programs that perform this translation. 


Interpreters 


oe The BASIC Interpreter translates your BASIC program 
line by line as your program is running. For a BASIC 
statement to be carried out, the interpreter must 
analyze the statement, check for errors, then perform 
the BASIC function requested. 


If a statement is performed more than once (inside a 
FOR...NEXT loop, for example), this translation 
process must be repeated each time the statement is 
performed. 


1-3 


1-4 


Interpreter Source Code 


BASIC stores your program as a linked list of 
numbered lines. This means the computer doesn’t 
know exactly where in memory each line is. When you 
branch to a particular line (using a GOTO or GOSUB, 
for example), the interpreter must search through every 
line in a program, starting with the first, until the 
particular line number is found. 


The interpreter maintains a list of the variables in your 
program in a similar way. When you use a variable in a 
BASIC statement, this list must be searched from the 
beginning until the variable is found. 


Compilers 


A program that is input to the compiler for translation 
is composed of One or more source code statements and 
is called a source file. Source files must be in ASCII 
format (a text file). BASIC source files can be 

YY identified by the filename extension .BAS. 


Unlike the interpreter, BASIC Compiler 2.00 translates 
all source code before you actually run your program; 
that is, the alternating process of translation and 
execution for each statement does not occur. In 
addition, memory addresses are associated with 
variables and with the targets of GOTOs and GOSUBs, 
during compilation, so that lists of variables or of line 
numbers do not have to be searched while your 
program is running. 


Once the compiler has translated the entire program 
into object code (machine language), it places the code 
in a special file called an object file. The object file is 
given the filename extension .OBJ. 


Y Finally, the object file produced by the compiler must 
be input to the Linker and made into an executable run 
file which is given the filename extension .EXE. The 
run file can then be executed by entering the filename. 


Compiler Source Code 
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Some compilers are known as optimizing compilers. 
Optimizing compilers perform such operations as the 
changing of the order of expressions and the 
elimination of common subexpressions. These 
operations can improve program performance and/or 
decrease the size of your program. 


Optimization and the elimination of the translation step ‘> 
when your program is running combine to make your 
program run faster. 


The BASIC Compiler 2.00 


The BASIC Compiler 2.00 is an optimizing compiler 
designed to complement the BASIC Interpreter. 


Creating application programs with the IBM Personal 
Computer BASIC Compiler 2.00 provides several 
benefits: 


e Increased speed of execution for most programs 
when compared to the interpreter version. ~~ 


e BASIC source code security. 


e Ability to make use of all available machine 
memory. 


e Line numbers are not necessary. 


A compiled program is optimized machine code, not 
source code. Consequently, compiling substantially 
improves execution time and protects your source 

program from unauthorized alteration or disclosure. 


Another advantage of the BASIC Compiler 2.00 is that, 
since the BASIC Compiler 2.00 has been created to 
support most of the interpreted BASIC language, the 
interpreter and the compiler complement each other. 


Therefore you have a powerful programming 
environment in which you can quickly run and debug 
programs using the BASIC Interpreter, and then later 
compile those programs to increase their speed of 
execution. 


~- BASIC Compiling Process 


This is a description of the BASIC programming 
process using the compiler. 


The Runtime Module 


Licensing Agreement a 
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A feature of the BASIC Compiler 2.00 is the ability to 
create programs to use the runtime module. The 
runtime module is a file named BASRUN20.EXE, and 
it contains most of the routines needed to implement 
the BASIC language. It can be thought of as a library 
of routines, with the unusual characteristic of being an 
executable file. 


The runtime module is loaded when program execution 
begins; it is not reloaded when the program chains to 
another program. The BASIC routines that are part of 
the runtime module do not need to be saved on diskette 
as part of your final compiled (executable) program. 
Therefore, if you create an application consisting of 
several programs that use the runtime module, you can 
Save a Significant amount of duplicate code and diskette 
space. Refer to ““The BASRUN20.EXE Runtime 
Module” in the chapter ‘““Compiling BASIC Programs,” 
later in this book, for more information on the runtime 
module. 


Application programs that require the runtime modules 
BASRUN20.EXE, REBUILD.EXE or ISAM.EXE, 
cannot be distributed without entering into a license 
agreement with IBM. A copy of the license agreement 
can be obtained by writing to IBM at: 


P.O. Box 2910 
Delray Beach, Florida 33444 
Attn: Personal Computer Customer Relations 


Note, however, that by compiling with the /O 
parameter, it is possible to develop programs with the 
BASIC Compiler 2.00 that do not use the 
BASRUN20.EXE runtime module, and, therefore, do 
not require the license agreement. This does not apply 
for ISAM.EXE or REBUILD.EXE. 


Chapter 2. Setting Up Your Compiler — 
The First Time Through 
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Introduction 


The purpose of this chapter is to help you set up your 
BASIC Compiler. We guide you step-by-step through 
the setup procedure. 


Files on Your Diskettes 


The BASIC Compiler master diskettes consist of the 
following: 


The BASIC diskette that contains these files: 


BASCOM.EXE — the BASIC Compiler 2.00 
LINK.EXE — the Linker (LINK) program 
DEMO.BAS — a demonstration program 
BASCOM20.LIB — the BASIC library 
BASRUN20.EXE — the runtime module 
BASRUN20.LIB — the runtime module library 
IBMCOM.OBJ — the communications module. If 
your program contains communications statements 
and you specify the /O parameter at compiletime, 
you must link this module to enable 
communications I/O. 


« IBMCAS.OBJ — the cassette module. If you have 
a cassette port, use cassette I/O and specify the 
/O parameter at compiletime, you must link this 
module to enable cassette I/O. 


° SMALLERR.OBJ — short error-message module. 
Linking this module causes error messages to be 
displayed in an abbreviated form. 


« SAMPLE1.BAT —a sample batch file 
¢« SAMPLE2.BAT — a sample batch file 


The ISAM diskette contains these files: 


LIB.EXE — object module library manager 

ISAM.EXE — the main ISAM program 

ISAM.INC — An include file 

ISMSHELL.BAS — ISAM template program 
REBUILD.EXE -— a utility to rebuild ISAM files 
MAIL.BAS — a demonstration program (> 
MAIL.H — an include file 

MAIL.DAT — a sample data file 

MAIL.KE — a sample data file. 


The First Time Through 


Important: You should back up your BASIC Compiler 
2.00 master diskettes, BASIC and ISAM, as soon as 
possible. 


Use the DOS DISKCOPY command. This formats the 

diskette and copies the DOS master files to your 

backup diskettes. Refer to the IBM Personal Computer “A 
DOS Reference for more information about 

DISKCOPY. 


Throughout this book, the phrase ‘‘BASIC diskette”’ 
refers to the backup copy of the BASIC master 
diskette. Store your master diskettes in a safe place and 
work with the backup copies. 


Important: The diskettes supplied with this product are 
double-sided. You get an error message if your system 
has single-sided diskette drives. 


We recommend that you compile the demonstration 
program before compiling any other programs because 
this sample session gives you an overview of the entire 


compilation process. Aa 
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If you have a one-diskette or two-diskette drive system, 
you are now ready to compile the demonstration 
program. 


If you have a fixed disk drive system, go to the next 
section, “‘Setup for a Fixed Disk System,” for further 


© instructions. 


Setup for a Fixed Disk System 


The diskettes you will be working with are: 
e A backup of the BASIC diskette 


e A backup of the ISAM diskette. 


Start Setup 


1. Start DOS and be sure the following prompt is 


displayed: 
or C> 


2. Insert your BASIC diskette in drive A. 


3. Use the DOS COPY command to copy all the files 
from the BASIC diskette to the fixed disk. 
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This is easily accomplished with the following 
command: 


COPY As 37.1: 
4. Remove the BASIC diskette. 
5. Insert your ISAM backup diskette in drive A. ‘> 
6. Use the DOS COPY command to copy all the files 

from the ISAM backup to the fixed disk. This is 


easily accomplished with the following command: 


COPY Aste Cs 


7. Now you are ready to compile the DEMO 
program. We recommend that you compile the 
demonstration program before compiling any other 
programs because this sample session gives you an 
overview of the entire compilation process. 


Installing BASIC Compiler 2.00 onto 
the IBM PC Network 


In addition to the files listed under “‘Files on Your 
& Diskettes’’, the ISAM diskette contains the following 
files: 


e NETINST.BAT 


e CHANGEIT.COM 


To install the compiler onto the disk server, follow 
these steps: 


1. Insert the ISAM diskette into drive A. 
2. aeiter, 

A: 

to make drive A the default. 
3... Enter: 


NETINST d 


where d is the drive letter used by remote users to 
access the \APPS directory. 


4. Follow the prompts to install BASIC Compiler 
2.00 


Linking BASIC Compiler 2.00 Programs 


To link programs compiled with the BASIC Compiler 
2.00 from the server machine, follow these steps: 


}. “Enter: 
QLINK ‘y 
to start the LINK batch file. 

2. When the library name prompt is displayed, enter: 
C:\ APPS \ BASCOM20\ 


To link programs compiled with the BASIC Compiler 
2.00 from a remote machine, follow these steps: 


1. Eater: 
QLINK 
to start the LINK batch file. 
2. When the library name prompt is displayed, enter: a 


d: \ BASCOM20\ 


where d is the drive letter you use to access 
applications on the server. 


Starting the Compiler 


Once installed, you can use the following commands to 
Start the compiler: 


eS First Form 


QBASCOM2 


Second Form 
d: \ BASCOM20 \ BASCOM 


where d is the drive letter used by remote users to 
access the \ APPS directory. 


Note: Check with the person responsible for 
installing applications on the server. Start-up 
procedures can vary, depending on how your 
particular system was installed. 


Using Optional Parameters with the BASIC 
Compiler 


If you are sharing BASIC Compiler with a remote and 
want to use optional parameters when you start it, use 


the following command: 2 
C:\ APPS \ BASCOM20\ BASCOM parameters 


Note: You can insert the command into your own 
batch files or you can use the command at the DOS 
prompt. The parameters are described in BASIC 
Compiler Fundamentals. 


If you are using BASIC Compiler from the network and 
want to use optional parameters when you start it, use 
the following command: 

d:\BASCOM20\ BASCOM parameters 


Note: Replace d: with the drive specifier for the 
network drive that contains applications. 


— 


For Applications Developers 


Some applications write information from the screen 
buffer to a network file or read information from a 
network file to the screen buffer. If the size of the data 

& transferred is larger than the size of the network /NBS 
buffer, users may see unpredictable results. 


If you are writing an application, do not transfer data to 
and from the screen buffer and a network file. Instead, 
transfer data from the screen buffer to a local buffer and 
then to the network file. 


If you choose to transfer data to and from the screen 
buffer and a network file, network users must increase 
the value of the /NBS parameter of the NET START 
command. The /NBS buffer should be as large as the 
screen buffer. 


Note: If you increase /NBS to a value larger than 

16K bytes, you must also specify /NBC:1. Using 

/NBS larger than 16K bytes may cause some 
‘oe performance loss. 


For Applications Users 


If you are using an application and get unexpected 
characters on your screen, your application may be 
trying to save or load information from the screen to a 
network file. Here are two methods of correcting this 
condition: 


METHOD 1: First save the information from the 
screen buffer to a local file. Then, copy the local file to 
the network file. 


To load information from a network file to the screen 
buffer, load the information from the network file to a 
local file. Then, load the local file to the screen buffer. 


METHOD 2: Increase the size of the network buffer 
space by doing the following: 


1. Exit the application. 

2. Restart the PC Network Program with the NET 
START command. Be sure to include the /NBS 
parameter and increase the size of the buffer to be at 
least 2K bytes. cy 

3. Restart the application. 


If the problem reoccurs, repeat steps | through 3 
and increase the size of the /NBS parameter again. 
You may need to use a value of up to 32K bytes. 


Note: If you increase /NBS to a value larger 
than 16K bytes, you must also specify /NBC:1. 
Using /NBS larger than 16K bytes may cause 
some performance loss. 


Chapter 3. Sample Session: Compile, 


Link, and Run 
Contents 

Tite Demo Program ie eis oo ses eee on 3-3 
Two-Diskette-Drive System .............000. 3-4 

Compiling the DEMO Program ............ 3-4 

Linking the DEM@ Program =). us ee 3-8 

Running the DEMO Program ............ 3-10 
One-Diskette-Drive System ................ 3-11 

Compiling the DEMO Program ........... 3-11 

Linking the DEMO) Paget oe 3-14 

Running the DEMO Progam =... ce 3-18 

Fixed Disk System: «(0 see aes ss eee se 3-19 

& Compiling the DEMO Program ........... 3-19 
Linking the DEM@) Pige@ee >. ore. 3-22 

Running the DEMO Program... 2.0.5.5... 3-25 

Usner a Batch File | fs oe a ew ea se 3-26 


Same Batch Piles |... 3.< gees. + kaa ee ee 3-26 


3-2 


The Demo Program 


This section uses a demonstration program to illustrate 
the step-by-step process for using the BASIC Compiler 
2.00. We include instructions for two-drive, one-drive, 


YY and fixed disk systems. 


The five steps in developing a program with the BASIC 
Compiler 2.00 are: 


1. Creating a source file 
2. Debugging 

3. Compiling 

4. Linking 

5. Running the program. 


If you enter commands exactly as described in this 
section, you should have a successful session with the 
BASIC Compiler 2.00. If a problem does arise, check 
and redo each step carefully. 


Because we have prepared a debugged demonstration 

vy program (DEMO.BAS), you do not have to perform 
the first two steps in the program development process. 
Therefore, the demonstration begins with compilation. 
The BASIC compiler can only read files in ASCII 
format, hence, the demonstration program on your 
diskette is in ASCII format. 


Two-Diskette-Drive System 


Compiling the DEMO Program 


Before you start, make sure you have created the ‘ty 
BASIC diskette. If you have not, go back to Chapter 2. 


1. Start DOS in drive A. 
2. Remove the DOS diskette. 
3. Insert the BASIC diskette into drive A. 
4. Label a blank, formatted diskette: 
BASIC Programs 
5. Insert the BASIC Programs diskette into drive B. 
6. Use the DOS COPY command to copy 


DEMO.BAS from the BASIC diskette to the A 
BASIC Programs diskette. 


To Baier 

B: 

This changes the default drive to B. 
8. . Bier: 

PATH A:\ 

This sets up a path to drive A. 


9. Enter: 


BASCOM 
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10. 


Lt; 


The following is displayed: 


IBM Personal Computer BASIC Compiler 
(C)Copyright IBM Corp 1982, 1983, 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1982, 1983, 1984, 1985 


Source filename [.BAS]: __ 
Enter: DEMO/E 


The /E is necessary because the DEMO program 
contains error-trapping statements, and does not 
compile properly unless you supply the /E 
parameter. 


It is not necessary to enter the .BAS filename 
extension because the compiler automatically 
assigns the extension. The following prompt is 
displayed: 


Object filename [DEMO.OBJ]: 


Object filename is the name you want the object 
(machine-readable) file to have. 


In our case, we want to name the object file 
DEMO.OBSJ, so just press the Enter key. The 
object file (output from the compiler) is put on 
your BASIC Programs diskette in drive B. 


The next prompt looks like: 
Source listing [LNUL.LST]:_ 
Source listing is the name you wish to give to the 


file that contains the compiled program listing. If 
you do not want a listing, press the Enter Key. 
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Le 


This gives you the default filename NUL.LST, 
which tells the compiler not to create a listing file. 


For our example, we want a listing file, so enter 
‘“‘DEMO” as shown: 


Source listing LNUL.LST]: DEMO 


Note: The compiler adds the default 
extension and produces the listing file 
DEMO.LST on your Programs diskette. 


This is what the completed session looks like if you 
use the filenames for the above examples: 


IBM Personal Computer BASIC Compiler 
(C)Copyright IBM Corp 1982, 1983, 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1982, 1983, 1984, 1985 


Source filename [.BAS]: DEMO/E 
Object filename [DEMO.OB3J]: 
Source listing [NUL.LST]: DEMO 


As soon as you enter the last filename, the 
compiler begins compiling the BASIC source file. 
If the program contains any errors, they are 
displayed on the screen as well as in the source 
listing. 


In our case, the DEMO program has no errors, so 
when the compiler is finished, the following is 
displayed: 


nnnnn Bytes Available 
nnnnn Bytes Free 


0 Warning Error(s) 
0 Severe Error(s) 


Bytes Available 
is the initial amount of compiler 
workspace available for storing the 
symbol table and the line number 
table, and for working storage for 
optimization and code generation. 


vy Bytes Free is the size of unused compiler 
workspace after the compiler has 
finished. If this number is less than 
1024, you are approaching the 
maximum program size for the 
amount of memory in your computer. 


Note: The numbers “‘nnnnn’”’ depend on the 
amount of memory in your computer. 


Control is then returned to DOS. 
13. At this point in the demonstration run, you can 


view or print the source listing file (DEMO.LST). 
To get a printed listing, press Ctrl-PrtSc. 


vy This echoes screen output to the printer. 
14. Enter: 
TYPE DEMO.LST 


The listing file is simultaneously printed on your 
printer and displayed on your screen. 


15. When the file has been printed, press Ctrl-PrtSc. 
This terminates printer echo. 


Note: A second way to print the file is to use 
the DOS command: 


COPY DEMQOVLEST LP Ti: 


You are now ready to go on to linking. 
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Linking the DEMO Program 


Use the following steps to link your program: 
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+; 


Enter: 


LINK 


The Linker is loaded and, after a short time 
displays a heading and the following prompt: 


IBM Personal Computer Linker 
Version 2.30 (C)Copyright IBM Corp 1981, 1982, 1983, 1984 


Object Modules [.OBJ]: __ 


Object Modules is the name of the 
machine-readable files created by the compiler. 
The .OBJ extension is not needed here. 


Enter DEMO as shown below: 


Object Modules [.OBJ]: DEMO 


Note: When linking multiple modules, 
specify each successive module with a plus 
sign (+). Suppose, for example, that you are 
linking three modules named DEMO.OBJ, 
DEMO1.OBJ, and DEMO2.OBJ. You can 
enter this response to the Linker prompt: 


Object Modules [.QBJ]: DEMO+DEM01+DEMO02 


See the LINK chapter in your DOS manual 
for details on linking multiple modules. 


The next prompt is: 


Run File [DEMO.EXEJ:_ 


Run File is the name you wish to give to the file 
that contains the executable code for your 
program. You can give the file another name, to 
which the Linker adds the filename extension 
.EXE. (you cannot override this filename 
extension), or just use the default, DEMO.EXE. 
For our example, just press the Enter key. 


The next prompt is: 


List File LNUL.MAP]: _ 


List File is the name you want to give to the file 
that contains a Linker-produced output listing. If 
you do not want a listing, press the Enter key. 
This gives you the default filename NUL.MAP, 
which tells the Linker not to create a listing file. 
For our example, we do want a listing, so enter 
DEMO as shown below: 


List File LNUL.MAP]: DEMO 


The Linker adds the default extension and 
produces the List File DEMO.MAP. 


The next prompt is: 
Libraries [.LIBJ:_ 
Libraries refers to the runtime routines needed to 


run your program. In response to this prompt, 
type: 


A: 


Press Enter. 
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Here is what this sequence of prompts looks like if you 
used our example filenames: 


LINK 


IBM Personal Computer Linker 
Version 2.30 (C)Copyright IBM Corp 1981, 1982, 1983, 1984 


Object Modules [.OBJ]: DEMO ‘> 
Run File [DEMO.EXE]: 

List File [NUL.MAP]: DEMO 

Libraries [.LIB]:A: 


The Linker now begins to link the program. When 
linking is completed, you have the Run File named 
DEMO.EXE stored on your diskette in drive B. We 
recommend that you display the directory of the 
diskette to confirm that the Run filename is there (it 
has the .EXE filename extension). Using our example 
filename, you would see DEMO.EXE listed in the 
directory. 


For more information on linking, see ‘““The LINK 
Program” in Disk Operating System Reference. 


Running the DEMO Program % 


Once you have compiled and linked your program, it is 
simple to run it. From DOS, enter the program 
filename, without its .EXE extension. For this 
demonstration, enter: 


B>DEMO 
The runtime module, BASRUN20.EXE, is loaded into 


memory by your program and your compiled program is 
executed. 
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One-Diskette-Drive System 


Compiling the DEMO Program 


Before you start, make sure you have created the 
BASIC diskette. If you have not, go back to Chapter 2. 


ie 


we 


22 


Start DOS in drive A. 

Remove the DOS diskette. 

Insert the BASIC diskette into drive A. 
Label a blank, formatted diskette: 

BASIC Programs 

Use the DOS COPY command to copy 
DEMO.BAS from the BASIC diskette to the 
BASIC Programs diskette. 


Remove the BASIC Programs diskette from drive 
A. 


Insert the BASIC diskette into drive A. 
Enter: 
BASCOM 


The following is displayed: 


IBM Personal Computer BASIC Compiler 
(C)Copyright IBM Corp 1982, 1983, 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1982, 1983, 1984, 1985 


Source filename [.BAS]: __ 


Remove the BASIC diskette from drive A. 


10. Insert the BASIC Programs diskette into drive A. 
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11. Enter: DEMO/E 


The /E is necessary because the DEMO program 
contains error-trapping statements, and does not 
compile properly unless you supply the /E 
parameter. 


It is not necessary to enter the .BAS filename ty 
extension because the compiler automatically 

assigns the extension. The following prompt is 

displayed: 


Object filename [DEMO.0BJ]: 


Object filename is the name you want the object 
(machine-readable) file to have. 


12. In our case, we want to name the object file 
DEMO.OBJ, so Enter: 


DEMO 


The object file (output from the compiler) is put 
on your BASIC Programs diskette in drive A. 


The next prompt looks like: 
Source listing LNUL.LST]:_ 


Source listing is the name you wish to give to the 
file that contains the compiled program listing. If 
you do not want a listing, press the Enter Key. 
This gives you the default filename NUL.LST, 
which tells the compiler not to create a listing file. 


13. For our example, we want a listing file, so enter 
“DEMO” as shown: 


Source listing LNUL.LST]: DEMO 


Note: The compiler adds the default 
extension and produces the listing file 
DEMO.LST on your Programs diskette. 


This is what the completed session looks like if you 
have used the filenames provided above: 


IBM Personal Computer BASIC Compiler 
(C)Copyright IBM Corp 1982, 1983, 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1982, 1983, 1984, 1985 


Source filename [.BAS]: DEMO/E 
Object filename [DEMO.OBJ]: 
Source listing [NUL.LST]: DEMO 


When you enter the last filename, the compiler 
begins compiling the BASIC source file. If the 
program contains errors, they are displayed on the 
screen and in the source listing. 


In our case, the DEMO program has no errors, so 
the compiler produces the following message on 
your display: 


nnnnn Bytes Available 
nnnnn Bytes Free 


O Warning Error(s) 
QO Severe Error(s) 


Bytes Available 
is the initial amount of compiler 
workspace available for storing the 
symbol table and the line number 
table, and for working storage for 
optimization and code generation. 


Bytes Free is the size of unused compiler 
workspace after the compiler has 
finished. If this number is less than 
1024, you are approaching the 
maximum program size for the 
amount of memory in your computer. 
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14. 


i: 


16. 


Note: The numbers ‘‘nnnnn’”’ depend on the 
amount of memory in your computer. 


Control is then returned to DOS. 

At this point in the demonstration run, you can 

view or print the source listing file, DEMO.LST. ‘> 
Press Ctrl-PrtSc. This echoes screen output to the 

printer. 

Enter: 


TYPE DEMO.LST 


The listing file is simultaneously printed on your 
printer and displayed on your screen. 


When the file has been printed, press Ctrl-PrtSc. 
This terminates printer echo. 


Note: A second way to print the file is to use 
the DOS command: 


COPY DEMO.LST LPT1: “A 


You are now ready to go on to linking. 


Linking the DEMO Program 


Use the following steps to link your program: 


1. 


Remove the BASIC Programs diskette from drive 
A. 


Insert the BASIC diskette in drive A. 


Enter: 


LINK “a 


The Linker is loaded and, after a short time, displays a 
heading and the following prompt: 


IBM Personal Computer Linker 
Version 2.30 (C) Copyright IBM Corp 1981, 1985 


Object Modules [.OBJ]: __ 


Object Modules is the name of the machine-readable 
files created by the compiler. The .OBJ extension is not 
needed here. 


4. Enter B:DEMO as shown below: 


Note: Although your system has only one 
physical drive, the system can recognize it by a 
different /ogical name. This enables your 
system to appear, to the Linker, as though it 
has two separate drives. 


Object Modules L.OBJ]: B:DEMO 


5. The next prompt is: 


Y Run File [DEMO.EXE]J:_ 


Run File is the name you wish to give to the file 
that contains the executable code for your 
program. You can give the file another name, to 
which the Linker adds the filename extension 
.EXE (you cannot override this filename 
extension), or just use the default name, 
DEMO.EXE. For our example, enter B: DEMO, 
as shown: 


Run File [DEMO.EXE]: B:DEMO 
6. The next prompt is: 


Y List File [NUL.MAP]:_ 


List File is the name you wish to give to the file 
that contains Linker-produced output listing. 
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If you do not want a listing, press the Enter key. 
This gives you the default filename NUL.MAP, 

which tells the Linker not to create a listing file. 
For our example, we do want a listing, so enter 

B:DEMO as shown below: 


List File LNUL.MAP]: B:DEMO 


The Linker adds the default extension and 
produces the List File DEMO.MAP. 


The next prompt is: 
Libraries [.LIB]:_ 


Libraries refers to the runtime routines needed to 
run your program. In response to this prompt, 
press the Enter Key. 


Here is what this sequence of prompts looks like if 
you used our example filenames: 


LINK 


IBM Personal Computer Linker 
Version 2.30 (C) Copyright IBM Corp 1981, 1985 


Object Modules [.OBJ]: B: DEMO 
Run File [DEMO.EXE]: 

List File [NUL.MAP]: B: DEMO 
Libraries [.LIB]: 


Remove the BASIC Programs diskette from drive 
A. 


Insert the BASIC diskette into drive A. 


After the libraries are loaded, the following prompt 
appears: 


Cannot find DEMO.OBJ. 
Change diskettes and hit <ENTER> a“ 


10. 


rt: 


oa. 


13. 


14. 


|e 


Insert the BASIC Programs diskette and press 
enter. 


The following prompt appears: 


Cannot find library: A:BASRUN20.LIB 
Enter new library spec: 


Enter: 
B: 
The following prompt appears: 


Insert diskette for drive B: and strike 
any key when ready 


Insert the BASIC diskette and press Enter. 
The following prompt appears: 


Insert diskette for drive A: and strike 
any key when ready 


Insert the BASIC Programs diskette and press 
Enter. 


The following prompt appears: 


Insert diskette for drive B: and strike 
any key when ready 


Insert the BASIC diskette and press enter. 
The following prompt appears: 


Insert diskette for drive A: and strike 
any key when ready 


Insert the BASIC Programs diskette and press 
Enter. 
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The Linker now begins to link the program. When 
linking is completed, you have the Run File named 
DEMO.EXE stored on your BASIC Programs diskette. 
We recommend that you display the directory of the 
diskette to confirm that the Run File filename is there 
(it has the .EXE filename extension). Using our 
example filename, you would see DEMO.EXE listed in 
the directory. 


See ‘““The LINK Program” in Disk Operating System 
Reference for complete details on the linking process. 


Running the DEMO Program 


Once you have compiled and linked your program, it is 
simple to run. At the DOS prompt, enter the program 
filename without its .EXE extension. For this 
demonstration, enter: 


A>B:DEMO 


The runtime module, BASRUN20.EXE, is loaded into 
memory by your program. 


Fixed Disk System 


= 


fo 


© Compiling the DEMO Program 


Start DOS from any drive. 

Insert the BASIC diskette into drive A. 

Make sure that drive C is your default drive. 

Use the DOS COPY command to copy the entire 
contents of the BASIC diskette onto drive C. This 


is easily accomplished with the following 
command: 


COPY Ask 

Remove the BASIC diskette from drive A. 

Insert the ISAM diskette in drive A. 

Use the DOS COPY command to copy the entire 
contents of the ISAM diskette onto drive C. This 
is easily accomplished with the following 
command: 

COPY Art Ca 

Enter: 

BASCOM 

The following is displayed: 


IBM Personal Computer BASIC Compiler 
(C)Copyright IBM Corp 1982, 1983, 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1982, 1983, 1984, 1985 


Source filename [.BAS]: __ 
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9. Enter: DEMO/E 


The /E is necessary because the DEMO program 
contains error-trapping statements, and does not 
compile properly unless you supply the /E 
parameter. 


It is not necessary to enter the .BAS filename 
extension because the compiler automatically 
assigns the extension. The following prompt is 
displayed: 


Object filename [DEMO.0BJ]: 


Object filename is the name you want the object 
(machine-readable) file to have. 


10. In our case, we want to name the object file 
DEMO.OBJ, so just press the Enter key. The 
object file (output from the compiler) is put on 
drive C. 


The next prompt looks like: 
Source listing LNUL.LSTJ:_ 


Source listing is the name you wish to give to the 
file that contains the compiled program listing. 


11. For our example, we want a listing file, so enter 
‘““‘DEMO” as shown: 


Source listing LNUL.LST]: DEMO 


Note: The compiler adds the default 
extension and produces the listing file 
DEMO.LST on your Programs diskette. 


If you do not want a listing, press the Enter Key. 


This gives you the default filename NUL.LST, “a 
which tells the compiler not to create a listing file. | 
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This is what the completed session looks like if you 
use the filenames for the above examples: 


IBM Personal Computer BASIC Compiler 
(C)Copyright IBM Corp 1982, 1983, 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1982, 1983, 1984, 1985 


Source filename [.BAS]: DEMO/E 
Object filename [DEMO.OB]J]: 
Source listing [NUL.LST]: DEMO 


As soon as you enter the last filename, the 
compiler begins compiling the BASIC source file. 
If the program contains errors, they are displayed 
on the screen as well as in the source listing. 


In our case, the DEMO program has no errors, so 
when the compiler is finished, the following is 
displayed: 


nnnnn Bytes Available 
nnnnn Bytes Free 


0 Warning Error(s) 
0 Severe Error(s) 


Bytes Available 
is the initial amount of compiler 
workspace available for storing the 
symbol table and the line number 
table, and for working storage for 
optimization and code generation. 


Bytes Free is the size of unused compiler 
workspace after the compiler has 
finished. If this number is less than 
1024, you are approaching the 
maximum program size for the 
amount of memory in your computer. 
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56 


14. 


Note: The numbers “‘nnnnn”’ depend on the 
amount of memory in your computer. 


Control is then returned to DOS. 


. At this point in the demonstration run, you can 


view or print the source listing file, DEMO.LST. 
To get a printed listing, press Ctrl-PrtSc. This 
echoes screen output to the printer. 

Enter: 


TYPE: DEMO.LST 


The listing file is simultaneously printed on your 
printer and displayed on your screen. 


When the file has been printed, press Ctrl-PrtSc. 
This terminates printer echo. 


Note: A second way to print the file is to use 
the DOS COPY command: 


COPY DEMO.LST LPTI: 


You are now ready to go on to linking. 


Linking the DEMO Program 


Use the following steps to link your program: 


r 
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Enter: 


LINK 


The Linker is loaded and, after a short time 
displays a heading and the following prompt: 


IBM Personal Computer Linker 
Version 2.30 (C) Copyright IBM Corp 1981, 1985 


Object Modules [.OBJ]: __ 


Object Modules is the name of the 
machine-readable files created by the compiler. 
The .OBJ extension is not needed here. 


Enter DEMO as shown below: 
Object Modules [.0BJ]: DEMO 


Note: When linking multiple modules, 
specify each successive module with a plus 
sign (+). Suppose, for example, that you are 
linking three modules named DEMO.OBJ, 
DEMO1.OBJ, and DEMO2.OBJ. You can 
enter this response to the Linker prompt: 


Object Modules [.OBJ]: DEMO+DEM0O1+DEM02 


See the LINK chapter in your DOS manual 
for details on linking multiple modules. 


The next prompt is: 


Run File (DEMO.EXEJ:_ 


Run File is the name you wish to give to the file 
that contains the executable code for your 
program. You can give the file another name, to 
which the Linker adds the filename extension 
-EXE (you cannot override this filename 
extension), or just use the default, DEMO.EXE. 
For our example, just press the Enter key. 


The next prompt is: 


List File CNUL.MAP]:_ 


List File is the name you wish to give to the file 
that contains a Linker-produced output listing. 
This gives you the default filename NUL.MAP, 
which tells the Linker not to create a listing file. If 
you do not want a listing, press the Enter key. For 
our example, we do not want a listing, so press the 


Enter key. Aa 


5. The next prompt is: 
Libraries [.018):. 


Libraries refers to the runtime routines needed to 
run your program. In response to this prompt, 
press the Enter key. 


Here is what this sequence of prompts looks like if you 
used our example filenames: 


LINK 


IBM Personal Computer Linker 
Version 2.30 (C) Copyright IBM Corp 1981, 1985 


Object Modules [.OBJ]: DEMO 
Run File [DEMO.EXE]: 

List File [NUL.MAP]: DEMO 
Libraries [.LIB]: 


The Linker now begins to link the program. When 
linking is completed, you have the Run File named 
DEMO.EXE stored on your fixed disk in drive C. We 
recommend that you display the directory of the 
diskette to confirm that the Run filename is there (it 
has the .EXE filename extension). Using our example 
filename, you would see DEMO.EXE listed in the 
directory. 


For more information on linking, see ““The LINK 
Program” in Disk Operating System Reference. 
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Running the DEMO Program 


Once you have compiled and linked your program, it is 
simple to run. From DOS, enter the program filename 
without its .EXE extension. For this demonstration, 
enter: 


w c>DENG 


DEMO loads the runtime module, BASRUN20.EXE, 
into memory and begins executing. 
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Using a Batch File 


The batch command facility of the Disk Operating 

System is a convenient way to automatically start the 

BASIC Compiler 2.00 and the Linker. See the IBM 

Personal Computer Disk Operating System manual for ‘> 
detailed information of the batch command facility. 


Several sample batch files are provided on the BASIC 
diskette. These files, identified by the filename 
extension .BAT, have been designed to demonstrate 
their utility; remarks are included to explain how they 
work. The batch files, SAMPLE1.BAT and 
SAMPLE2.BAT, are explained in this section. 


Sample Batch Files 


SAMPLE1.BAT can be used to compile, link, and run 
the DEMO.BAS program. This file assumes a 
two-drive system in which the BASIC diskette is in 
drive A and the BASIC Programs diskette is in drive B. 


SAMPLE2.BAT performs the same functions as 
SAMPLE1.BAT; however, this batch file assumes that 
your system has a fixed disk containing the necessary 
files. 


SAMPLE1.BAT — Two-Diskette-Drive System 


B: 

A:BASCOM %1,,%2; 

IF ERRGRLEVEL 226070 EXIT 
A:LINKeS! . RUE UR 3 

41 

EARLY 


See the ‘““Compiler Termination Codes” section in the 
chapter ‘““Compiling BASIC Programs”’ for details on 
the “IF ERRORLEVEL” batch statement. 
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The filename DEMO is used for the %1 replaceable 
parameter while the parameter /E is used for the %2 
replaceable parameter. The compiler translates 
DEMO.BAS and produces DEMO.OBJ and 
DEMO.LST. The batch file then calls the Linker, 
which produces the executable file DEMO.EXE. The 
runfile, DEMO.EXE, is then executed. 


To run this file with the demonstration program, 
DEMO.BAS, enter the following in response to the 
DOS prompt: 


SAMPLE1 DEMO /E 


SAMPLE2.BAT — Fixed Disk System 


BASCOM 21, ,%2 
IF-ERRORLEVEL> 2 GOVGe Bait 
LINK 21; 

1 

SEXET 


To run this file with the demonstration program, 
DEMO.BAS, enter the following in response to the 
yy DOS prompt: 


SAMPLE2 DEMO /E 


Note: A batch file must be accessible each time 
one of its statements is going to be executed. If 
the file is not found, DOS gives the following 
message: 


Insert disk with batch file 
and strike any key when ready 


When changing diskettes, it is convenient to have 
the batch file on all diskettes. 


3-28 
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Introduction 


This chapter explains how to compile BASIC programs 
using either diskettes or a fixed disk. If this is the first 
time you have used the BASIC compiler and you have 
not completed the setup steps in “‘Setting Up Your 
Compiler — The First Time Through,” return to 
Chapter 2. 


The first step in creating an executable BASIC program 
is writing and debugging the source code. Three IBM 
PC-compatible editors that can be used to develop your 
programs are listed here: 


The Line Editor (EDLIN) 
(part of your DOS package) enables you to 
specify and edit one line at a time. 


BASIC Program Editor 
(part of your built-in BASIC Interpreter) 
enables you to edit a line anywhere on the 
screen, but you can change only one line at a 


vy time. 


Personal Editor 
(available as a separate software package) 
allows you to make on-screen changes without 
regard to lines or line numbers. 


After you have created and debugged your BASIC 
source program, the next step is to compile it. During 
this step you can check out differences that may exist 
between the interpreter and the BASIC compiler. The 
compiler flags all syntax errors as it reads your source 
program. If compilation is successful, the compiler 
creates a relocatable object file. 


Note: Support for this compiler is limited to DOS 

Y Version 2.10 or later. If you try to run a compiled 
program with a previous version, you get an Error 
in EXE file message. 


Starting the Compiler 


You can start the BASIC Compiler 2.00 in either of 
two ways; your choice depends on your preference 
and/or how your system is configured. 


e You can let the BASIC Compiler 2.00 prompt you 
for the information it needs. If you have one 
diskette drive, you can change diskettes before you 
proceed with answering the prompts. 


e You can enter all the information the compiler 
needs on one command line. This is a fast way to 
start the compiler if you have two disk drives or a 
fixed disk. 


Letting the BASIC Compiler 2.00 Prompt 
You 


If you want to let the BASIC Compiler 2.00 prompt 
you for the information it needs, you can start it as 
follows: 


If you have a two-drive system, you would normally 
have B as the default drive. 


With the BASIC diskette in drive A, enter: 
A:BASCOM 


The BASIC Compiler 2.00 is loaded into your 
computer. After a short time, the compiler displays a 
heading and the following prompt: 


Source filename [.BAS]:_ 


Before you respond, insert the work diskette containing 
your program into a diskette drive. If your system has 
one diskette drive, you must remove the BASIC “ 
diskette and replace it with your work diskette. If you 

have a two-drive system, you would normally put your 

work diskette in drive B. 
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Source filename is the name of the file input to the 
compiler. Enter the name of the source file, that is, 
your program file. For example: 


Source filename [.BASJ]: myprog 


The name shown in the brackets [.BAS] is the default 
filename extension that the compiler uses if you do not 
specify your own filename extension. In this example, 
the compiler uses the file MYPROG.BAS on the 
default diskette drive. 


Note: The name MYPROG.BAS is used as an 
example only. You can choose any name provided 
it conforms to the rules detailed under ‘‘Filename’”’ 
in Chapter 6. 


After you enter the source filename, this prompt 
displays: 


Object filename LMYPROG.OBJ]:_ 


Object filename is the name you want the object file to 
have. If you wish to have your object file stored under 
the default name (in the brackets—M YPROG.OBJ in 
this example), simply press the Enter key. If you want 
the object file to have a different name, enter the name 
after the prompt. The compiler adds the extension 
-OBJ to the filename if you do not include a filename 
extension. 


The last prompt appears as: 
Source listing CNUL.LST]:_ 


Source listing is the name of the file that contains the 
compiled source listing. The source listing contains 
errors and other messages produced by the compiler, 
and is discussed in detail under ‘““Sample Compiler 
Listing.” 
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If you do not want a listing, press Enter. This gives you 
the default filename NUL.LST, which tells the compiler 
not to create a source listing file, although any messages 
are still displayed on the screen. If you want a listing, 
enter the name you want to give the listing file. The 
compiler adds the .LST extension if you do not include 
one in your filename. 


You may have the listing file printed out by answering 
this prompt with the device name of the printer. For 
example: 


source Tisting- (NUL .LSTI]:: tptl 


This method is a fast way to produce the printed listing, 
since it does not require the creation of a diskette file. 


Optional Compiler Parameters: You can specify 
optional compiler parameters by adding them to the file 
specification in response to any prompt. Each 
parameter must begin with a slash (/). Compiler 
parameters are discussed in the section ‘“‘Compiler 


Parameters.”’ ~ 


Using a Single Command Line 


The BASIC Compiler 2.00 can also be started by using 
the following command line: 


BASCOM  sourcefile, objectfile, listfile |parm]...[;] 
sourcefile is the name of your source file. 


objectfile is the name you want to give the object file 
that is created by the compiler. 


listfile is the name you want to give the listing 
file. 
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parm is an optional compiler parameter. Each 
parameter must begin with a slash (/). 
These parameters are explained in 
‘‘Compiler Parameters.” Take special note 
of the /O parameter, which affects the 
way you link and run your compiled 
program. 


Both the BASIC Compiler 2.00 (BASCOM.EXE) and 
your source file must be accessible on diskette when the 
command is executed. After you enter the command 
line from DOS, the BASIC Compiler 2.00 is loaded and 
immediately performs the tasks indicated by the 
command field. 


Variations on the Command Line: If you enter the 
complete BASCOM command line, as shown above, 
you are not shown the prompts for the filenames as 
described previously. 


If you do not specify all three files in the command line 
and do not end with a semicolon (;), the BASIC 
Compiler 2.00 prompts for the remaining unspecified 
files. If necessary, you may at this point remove the 
BASIC diskette to change diskettes. As explained 
previously under “Letting the BASIC Compiler 2.00 
Prompt You,” each prompt displays its default, which 
may be accepted by pressing the Enter Key, or 
overridden by entering your own file specification. 


If you do not include the source filename in the 
command line, the compiler asks for one. Parms 
(parameters) are never prompted for; they may be 
added to the end of the command line or to any file 
specification given in response to a prompt. 


If you do not specify all three filenames, but end the 
command line with a semicolon (;), the unspecified files 
are set to the defaults without further prompting. 


Here are some examples: 


BASCOM myprog.any 
The source file is MYPROG.ANY. The 
compiler prompts for the object file, 
showing a default name of 
MYPROG.OBJ. After a response is given, (‘> 
another prompt is displayed showing the 7 
default of NUL.LST. 


BASCOM myprog.any; 
If the semicolon is added, the compiler 
uses the default names for the remaining 
files: MYPROG.OBJ for the object file, 
and no source listing. 


BASCOM myprog.any,,; 
The comma overrides the “‘no listing”’ 
default for the source listing file. Instead, 
you get a listing file with the source 
filename and the extension .LST. For this 
example, you get an object file named 
MYPROG.OBJ and a source listing named 
MYPROG.LST. “a 


BASCOM myprog.any,, 
Using the same example, but without the 
semicolon, the source file MYPROG.ANY 
is compiled, the object file produced is 
named MYPROG.OBJ, but you get a 
prompt for the listing file with the default 
of MYPROG.LST. 


BASCOM myprog,,list 
This causes the compiler to use 
MYPROG.BAS as its source file, and to 
generate a MYPROG.OBJ, and a 
LIST.LST file. Even though the line does 
not end in a semicolon, no prompts are 
produced. a 


BASCOM myprog.any,nul,prn; 
This compiles the source program 
MYPROG.ANY, but no object file is 
produced; the source listing file is sent to 
the printer. This technique is useful for 
debugging. 


Compiler Parameters 


In addition to specifying filenames, extensions, and 
devices to direct the compiler to produce object and 
listing files, you can tell the compiler to perform 
additional or alternate functions by specifying extra 
parameters. 


Compiler parameters may be placed at the end of the 
command line after the file specifications, or after any 
file specification given in response to a prompt. 
Additional parameters may follow other parameters. 
For example, the following command line compiles a 
program named PROGRAM.BAS and includes the /D 
and /X parameters: 


BASCOM PROGRAM, ,LIST/D/X; 


Parameters signal special instructions to be used during 
compilation. The parameter tells the compiler to 
perform a special function or to alter a normal compiler 
function. More than one parameter may be used, but 
all must begin with a slash (/). Do not confuse these 
parameters with similar parameters on other IBM 
Personal Computer software products. 


The compiler parameters are described on the following 
pages. First, we’ll give you the detailed descriptions of 
each parameter. Then you’ll find a chart that 
summarizes the function of each parameter. 
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Error Trapping Parameters 


If your BASIC source program contains error trapping 

routines that involve the ON ERROR statement plus 

some form of a RESUME statement, you need to use 

one of the two error trapping parameters, /E or /X. 

Error trapping routines require line numbers in the ‘> 
object (.OBJ) file. If you do not use one of the error 

trapping parameters, the compiler does not include line 
numbers in the object file, and a compiler error results. 


The error trapping parameters allow you to use ON 
ERROR statements in your program. These statements 
can aid you in debugging your BASIC programs. Note, 
however, that extra code is generated by the compiler 
to handle ON ERROR statements. 


Parameter Action 


JE The /E parameter tells the compiler that 
the program contains an ON ERROR with 
a RESUME line construction. To handle 
ON ERROR properly, the compiler must 
generate extra code for the GOSUB and “A 
RETURN statements. Also, the compiler 
must include a line number address table 
(one entry per line number) in the binary 
file, so that each runtime error message 
includes the number of the line in which 
the error occurs. The /E parameter 
generates four extra bytes of code for each 
line number in your program. To save 
memory space and execution time, do not 
use this parameter unless your program 
contains an ON ERROR statement. 


Note: If you use any RESUME 

statement other than RESUME ine, 

or you use a combination of 

RESUME line with other RESUME ~ 
statements, use the /X parameter 

instead. 


/X The /X parameter tells the BASIC 
Compiler 2.00 that the program contains 
one or more RESUME, RESUME NEXT, 
or RESUME 0 statements. 


The /X parameter performs all the 
functions of the /E parameter, so the two 
need never be used at the same time. In 
addition, the /X parameter generates four 
extra bytes of code per statement. For 
example, the program line: 


20 X=7: Y=18 


consists of two statements, so 8 bytes of 
extra code are required when you use the 
/X parameter. 


Note that to handle RESUME statements 
properly, the compiler cannot optimize 
across statements. Therefore, do not use 
/X unless your program contains 
RESUME statements other than 
RESUME ine. 


Event Trapping Parameters 


If your BASIC source program uses event trapping 
(COM(n), KEY(n), PEN, STRIG(n)), TIMER, or 
PLAY(n), you must use one of the two event trapping 
parameters, /V or /W. These parameters tell the 
compiler to generate the extra code needed to check for 
the particular event at each line or at each statement. 


Parameter Action 


/V The /V parameter tells the BASIC 
Compiler 2.00 to include an event trap 
check at each statement. This parameter 
generates one extra byte of code per 
Statement. Also, the compiler cannot 
optimize as much as it can with /W. 


When you specify /V, the compiler can 
only optimize within a single statement, 
not across statements. Event trapping 
with the /V parameter most closely 
resembles event trapping in the interpreter. 


/W The /W parameter tells the compiler to ‘y 
add an event trap check at each line 
number. This parameter generates one 
extra byte of code for each line number in 
your program. If you are using event 
trapping, the /W parameter uses less space 
and takes less execution time than the /V 
parameter. If there is only one statement 
per line in the program, the /W parameter 
performs the same as the /V parameter. 


Convention Parameters 


The /4 and /T parameters affect the scanning and 
execution conventions of the compiler. These 
parameters allow you to compile and run programs that 
were written in another version of BASIC—in 
particular, Microsoft’s version 4.51. 


The convention parameters may be used together 
(/4/T). The action of each parameter is explained 
below: 


Parameter Action 


/4 The /4 parameter tells the compiler to use 
the scanning conventions of the Microsoft 
4.51 BASIC-80 Interpreter. Scanning 
conventions are the rules that the compiler 
uses to recognize the BASIC language. 


/T 


When you specify /4, the compiler follows 
these rules: 


e Spaces are not significant. 


° Variable names with imbedded 
reserved words are invalid. 


z Variable names are restricted to two 
significant characters. 


Use the /4 parameter to correctly compile 
a source program in which spaces do not 
delimit the reserved words. For example: 


FORI=ATOBSTEPC 


Without the /4 parameter, the compiler 
assigns the value of the variable 
ATOBSTEPC to the variable FORI. With 
/4, the compiler recognizes the line as a 
FOR statement. 


Note: The /4 and /N parameters 
cannot be used together. 


The /T parameter tells the compiler to use 
the Microsoft BASIC-80 Version 4.51 
execution conventions. ‘“‘Execution 
conventions” refers to the implementation 
of BASIC functions and commands and 
what they actually do when you run your 
program. In particular: 


e FOR...NEXT loops are always 
executed at least one time. 


e The value returned by POS and LPOS 
may range from 0 to width—1. (This 
differs from IBM Personal Computer 
BASIC in that the first column is 0, 
not 1.) 
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e The argument to TAB may range 
from O to 255, where, again, 0 is the 
leftmost column and width—1 is the 
rightmost column. If the current print 
position is already beyond space n, 
TAB(n) has no effect. 


e The argument to SPC may range from (> 
0 to 255. SPC(n) prints n spaces, 
even if n is greater than the defined 
width of the device (it does not do 
modulo arithmetic in this case). 


e When BASIC requires an integer, it 
truncates single-precision or 
double-precision values instead of 
rounding, except in INPUT 
statements. 


e The INPUT statement leaves the 
variables in the input list unchanged if 
only Enter is pressed. The ?Redo 
from start message is displayed only 
when an invalid response is given. In “a 
this case, a valid input list must be 
entered or the message ?Redo from 
start is displayed again. 


Special Code Parameters 


The BASIC Compiler 2.00 can generate code for 
special uses or situations. Some of these special code 
parameters cause the compiler to generate larger and 
slower code, so you should use them only when 
necessary. 


Parameter Action 


/A The /A parameter includes a listing of the a 
object code for each source line in the 
source listing. 
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The object code is in mnemonic (like 
assembly language) form. Normally, the 
source listing produced by the compiler 
consists of a listing of your BASIC source 
program with any error messages, plus the 
relative locations of your code and the size 
of your accumulated data area. If the /A 
parameter is set, the source listing also 
includes the object code generated for 
each statement. Use of this parameter 
gives you a longer listing file. Use it only 
if you want the additional information. 


The /C compiler parameter is similar to 
the /C: option you can use when you start 
Disk or Advanced BASIC from DOS. It 
sets the size of the buffer for receiving 
communications data. This parameter is 
specified as: 


/C:combuffer 


where combuffer is the desired size of the 
buffer. If the /C parameter is omitted, 
256 bytes are allocated to the receive 
buffer. The maximum size allowed is 
32767 bytes. For example, the command 
line: 


BASCOM COMTEST /C:1024; 


compiles the source program named 
COMTEST.BAS. The compiler generates 
a special call so that when the compiled 
program is run, the communications 
buffers is allocated to 1024 bytes. 


Note: A minimum of 256 bytes is 
always allocated to the 
communications receive buffer 
regardless of the size specified with 
the /C parameter. 


/D 


The /D parameter causes the compiler to 
generate debugging and error handling 
code. Use of /D allows you to use TRON 
and TROFF in your program. Without /D 
set, TRON and TROFF are ignored and 
the compiler generates a warning message. 


Note: Whenever TRON and TROFF 
appear in your program, your program 
must be written using line numbers. 


Note: You must compile with the 
/D parameter to effectively 
Ctrl-Break at runtime. If this 
parameter is not specified, you 
cannot break out of a compiled 
program in some situations. 


With /D, the BASIC Compiler 2.00 
creates larger and slower object code that 
performs the following checks: 


“ Arithmetic overflow: All numeric 
operations are checked for overflow 
and underflow. 


e Array bounds: All array references are 
checked to see if the subscripts are 
within the bounds specified in the 
DIM statement. 


e Line numbers: The generated object 
code includes line numbers so that 
errors that occur when you run your 
program indicate the line where the 
error occurred. 


e RETURN: Each RETURN statement 
is checked for a prior GOSUB 
statement. 


/N 


Without the /D parameter set, array 
bound errors, RETURN without GOSUB 
errors, and arithmetic overflow errors do 
not cause error messages when you 
compile your program. Additionally, error 
messages do not occur when you run your 
program, even though the program may 
run incorrectly. Use the /D parameter to 
make sure that you have thoroughly 
debugged your program. 


The /N parameter tells the compiler to 
relax line numbering constraints. When 

/N is specified, line numbers in your 
source file may be in any order, or they 
may be eliminated entirely. Any line 
numbers that exist have nothing to do with 
the sequence of the lines; they serve only 
as labels for GOSUBs, GOTOs, and any 
other statements that use line numbers as 
references for branching. 


Note: Alphanumeric labels can be 
used in place of line numbers as 
targets for branching statements. 


There are three advantages to using /N: 


e Elimination of line numbers increases 
program readability. 


e BASIC source code can more easily 
be included in a program using 
SINCLUDE—hence, the same block 
of code can be easily inserted into 
different programs. 


e The BASIC Compiler 2.00 optimizes 
over entire blocks of code rather than 
single lines (for example, in 
FOR...NEXT loops). 
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/R The /R parameter tells the compiler to 
store multidimensional arrays in row-major 
order. For a two-dimensional array, this 
means that the second subscript varies 
faster than the first. The default is 
column-major order. 


/S The /S parameter forces the compiler to ‘y 
write string constants more than four 
characters long to your .OBJ file on 
diskette as they are encountered, rather 
than keep them in memory as your 
program is compiled. Without /S, you can 
run out of memory space while the 
compiler is running if your program 
contains too many long string constants 
(quoted strings). 


The /S parameter allows programs with 

many quoted strings to take up less 

memory during compilation. However, it 

may increase the amount of memory 

needed to run your program, since 

identical strings may be coded several A 
times. Without /S, any references to 

identical strings are combined so that the 

String is only coded once in your final 

compiled program. 


/O The /O parameter tells the compiler to 
compile the program without using the 
runtime module BASRUN20.EXE. The 
following pages discuss the runtime 
module in more detail. 
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The BASRUN20.EXE Runtime Module 


If you do not specify the /O parameter, your program 
is compiled to use the BASRUN20.EXE runtime 
module. As explained under “‘Chapter 1. Introducing 
the BASIC Compiler 2.00,””» BASRUN20.EXE can be 
thought of as a library of routines, with the unusual 
characteristic of being an executable file. It contains 
the body of routines that, in essence, make up the 
BASIC language. Your compiled object file, on the 
other hand, implements the particular algorithm that 
makes your program a unique BASIC program. 


The runtime module contains more frequently used 
BASIC routines. If your program uses other less 
frequently used routines, these routines are searched for 
and found in BASRUN20.LIB when you link your 
program. 


A note for advanced programmers: 


The runtime module contains all routines called 
from BASCOM, except for calls to independently 
compiled BASCOM or assembly language 
modules. The library BASRUN20.LIB is linked 
with the compiled module to set up the entry 
condition to the runtime module. 


The runtime module is loaded when you run your 
program; both BASRUN20.EXE and your program 
reside in memory at the same time. Once loaded, 
BASRUN20.EXE takes up 60K bytes of memory when 
you run your program. 


Remember, you must enter into a license agreement 
with IBM before you distribute programs that use the 
runtime module. 
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Using the runtime module gives you the following 
advantages: 


Chaining works as in the interpreter. That is, files 
are left open, device status is preserved, and you 
can use COMMON to pass variables to the 
chained-to program. 


It may take less time to link, since unresolved 
external references do not have to be searched for 
in multiple library modules. 


When you specify the /O parameter to the compiler, 
the runtime module is not used by your program; 
instead, the BASCOM20.LIB library is searched when 
you link the program. 


The advantages of using /O are: 


For small programs, you may be able to compile 
and link programs that are smaller than the 
60K-byte minimum required to accommodate the 
BASRUN20.EXE module. 


Execution of a compiled and linked .EXE file does 
not require the existence of the runtime module on 
diskette when you run your program. 


There are, however, some disadvantages to using 4 


COMMON is not supported between programs. 
That is, the CHAIN command is semantically 
equivalent to the RUN command. 


Complete code for required BASIC routines is 
included in every .EXE file generated, thus 
increasing the size of each of your .EXE files. This 
is not the case for .EXE files that use the runtime 
module. 


Summary Chart of Compiler Parameters 


/E 


Error Program has ON 
Trapping ERROR with 
RESUME ine. 


Program has ON 
ERROR with 
RESUME, RESUME 
0, or RESUME 

NEXT. 


Event Perform event trap 
Trapping test at every 
statement. 


/W Perform event trap 
test at every line. 


Convention | /4 Use Microsoft 4.51 
scanning conventions 
(not allowed together 
with /N). 
At Use Microsoft 4.51 
execution 


conventions. 


/X 


Special JA 
Code 


Include listing of 
object code in the 
listing file. 


/C:combuf | Set size of 
communications 
buffer. 


/D Generate debug code 
for error checking 
when program runs. 


/N Relax line numbering 
constraints. 
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Store 
multidimensional 
arrays in row-major 
order. 


/R 


Write quoted strings 
to .OBJ file on 
diskette and not to 
data area in memory. 


Do not use 
BASRUN20.EXE 


runtime module. 


When the Compiler Finishes 


As soon as you enter the command line, or answer the 
last prompt, the compiler begins its work. If the 
program contains any syntax errors, these errors are 
displayed on the screen as well as in the listing file. 


YY When the compiler is finished, it displays a message 
with the number of errors it has found. The message 
appears on the screen as well as in the source listing and 
looks something like this: 


nnnnn Bytes Available 
nnnnn Bytes Free 


nnnnn Warning Error(s) 
nnnnn Severe” Error(s) 


Bytes Available 
is the initial amount of compiler workspace 
available for storing the symbol table and 
the line number table, and for working 
storage for optimization and code 
vY generation. 


Bytes Free is the size of unused compiler workspace 
after the compiler has finished. If this 
number is less than 1024, you are 
approaching the maximum program size 
for the amount of memory in your 
computer. 


If the compiler shows only warnings, you can generally 
continue with the next step, linking. You should check 
the “Messages” section of BASIC Compiler 2.00 
Language Reference to see what the actual messages 
mean. 


If the compiler has found errors, you must locate and 

wv fix those problems in your source program before you 
go to the linking step. Change your program, save it 
again (in ASCII format), and rerun the BASIC 
Compiler 2.00. 
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When the compiler is finished processing, control is 
returned to DOS. You can interrupt the compiler run 
before its normal completion by pressing Ctrl-Break. 


Compiler Termination Codes 


The compiler supplies an exit status to DOS that can be (> 
accessed with the IF ERRORLEVEL n batch 
command. The values returned by the compiler are: 


Value Meaning 

0 No warnings or errors issued. 

oe Warnings were issued, but no fatal error(s) 
occurred. 

4 Fatal errors encountered. 
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Debugging with the BASIC Interpreter 


The BASIC Interpreter can be used to check for syntax 
and logic errors in your source program. Note, 
however, that this is an optional step; it is certainly 
possible to create a program without ever running it 
with the interpreter. 


You may use some commands or functions in your 
source program that execute differently with the 
interpreter. In those cases, you probably need to use 
the compiler for debugging. The interpreter does not 
support double-precision loop counter variables as does 
the BASIC Compiler 2.00. 


Nevertheless, the language supported by the compiler is 
intended to be as similar to the BASIC Interpreter as 
possible. This means you can make the BASIC 
Interpreter your primary debugging tool, which saves 
you from doing unnecessary compilations and links. 
Also, the RUN, CONT, TRON and TROFF commands 
make the interpreter a very powerful interactive 
debugging tool. Refer to the IBM Personal Computer 
BASIC manual for more information on these 
commands. 


When using the interpreter as a debugging tool, 
consider this: The interpreter stops if an error occurs 
while a program is running. Any subsequent errors are 
not caught until the first detected error is corrected and 
the program is run again. The compiler, on the other 
hand, scans all the lines in your program and reports all 
the errors it detects. Therefore, you may find it helpful 
to compile your program first to catch syntax errors, 
then test the logic with the interpreter after you correct 
all the syntax errors. 


Chapter 5. Building a BASIC Source 
Program 
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Introduction 


This section provides general information about the 
components of a BASIC source program. Information 
is included on the following: 


vv e Line numbers 


* BASIC statements 


. Character set 
. Reserved words 


« Differences between the compiler and the 
interpreter. 


General Information about BASIC 
Programming 


Line Format 


Program lines in a BASIC Compiler 2.00 program can 
have any of the following formats: 


Format 1 


[line __ number] statement1|:statement2...| 


Format 2 


wv [numeric __ label] statement1|:statement2...| 
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Format 3 


lalpha__numeric__ label] statement1|:statement?2...] 


Where: 

line__number is an integer between 0 and 
65529. 

numeric __ label is any combination of digits 
and periods followed by a 
colon (:). 


alpha__numeric__label is any combination of letters, 
digits, and periods that begins 
with a letter or a period and 
ends with a colon (:). 


The use of labels allows the use of mnemonic labels to 
make your programs easier to read and maintain. 
Labels can be used as objects of most statements where 
line numbers are currently permitted, with the following 
exceptions: 


IF (condition) THEN (line number) 
and 
RUN (line number) 


In each of these cases, only a line number is permitted 
in the statement. However, for both of these cases, the 
explicit use of aGOTO statement allows a label to be 
used. For example: 


IF A>1@ THEN GOTO BAD.DATA 


To distinguish labels from keywords or variables, each 
label must be followed by a colon (:) when it starts a 
line. 


Note: If you wish to use error reporting (with the 
/E option) and error trapping, you must use line 
numbers. 


Numeric labels, alphanumeric labels, and line numbers 
can be intermixed in the same program. If there are no 
line numbers in your program, you must compile your 
© program with the /N switch. 


BASIC Statements 


A BASIC statement is either executable or 
nonexecutable. Executable statements are instructions 
that tell BASIC what to do next while running a 
program. For example, PRINT X is an executable 
statement. Nonexecutable statements, such as DATA 
or REM, contain information only and do not cause any 
program action when BASIC sees them. 


All statements are executable except the following: 
COMMON 
w DATA 
DEFDBL, DEFINT, DEFSNG, DEFSTR 
DIM (for static arrays only) 
OPTION BASE 


REM (including metacommands). 


All the BASIC statements are explained in detail in 
BASIC Compiler 2.00 Language Reference. 
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You can have more than one BASIC statement on a 
line, but each statement must be separated by a colon 
(:). The total number of characters cannot exceed 253, 
plus the Enter. For example: 


19 FOR I=1 TO 5: PRINT I: NEXT 


Results: ‘> 


Mm HWP Fe 


Comments 


Comments can be included at the end of a line. 
The single quote (’) separates the comment from the 
rest of the line. 


Character Set “A 


The BASIC character set consists of alphabetic 
characters (A—Z), numeric characters (O—9), and 
special characters. 
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The following special characters have specific meanings 


in BASIC: 


Character 


A 


— 


“VA 


Name 


blank 
equal sign 
plus sign 
minus sign 
asterisk 
slash 
backslash 


caret 

left parenthesis 
right parenthesis 
percent sign 
number sign 


dollar sign 
exclamation point 


ampersand 
comma 

period 

single quote mark 
semicolon 

colon 

less than 

greater than 


double quote mark 
underline 


Purpose 


delimiter 
assignment 
concatenation 
subtraction 
multiplication 
division symbol 
integer division or 
path delimiter 
exponentiation 
delimiter 
delimiter 
declares an integer 
declares a 
double-precision 
number 

declares a string 
declares a 
single-precision 
number 

denotes a hex or 
octal number 
delimiter, also 
controls print 
format 

decimal point 
denotes a remark 
controls print 
format 
statement 
separator 

logical operator 
logical operator 
string delimiter 
program line 
continuation 
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Many characters can be printed or displayed even 
though they have no particular meaning to BASIC. See 
‘“ASCII Character Codes,” in BASIC Compiler 2.00 
Language Reference for a complete list of these 
characters. 


Reserved Words % 


Certain words and letter combinations have special 
meaning to BASIC. They are called reserved words. 
Reserved words include all BASIC commands, 
statements, function names, and operator names. 
Reserved words cannot be used as variable names. 


Reserved words must be separated from data or other 
parts of a BASIC statement by blanks or special 
characters as allowed by the syntax. 


The following are reserved words in BASIC. 


ABS COMMAND$ 
AND COMMON 
ASC CONT 
ATN COS 
AUTO CSNG 
BEEP CSRLIN 
BLOAD CVD 
BSAVE CVI 
CALL CVS 
CALLS DATA 
CUBL DATES 
CHAIN DEF 
CHDIR DEFDBL 
CHR$ DEFINT 
CINT DEFSNG 
CARCLE DEFSTR 
CLEAR DELETE 
CLOSE DIM 

CLS DRAW 
COLOR EDIT 
COM ELSE 


END 

END SUB 
ENVIRON 
ENVIRON$ 
EOF 


PRINT 
PRINT# 
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PSET STRIG 


ror STRING$ 
RANDOMIZE SUB 
READ SWAP 
REDIM SYSTEM 
REM TAB( 
RENUM TAN 
RESET THEN 
RESTORE TIME$ 
RESUME TIMER 
RETURN TO 
RIGHT$ TROFF 
RMDIR TRON 
RND UNLOCK 
RSET UBOUND 
RUN USING 
SAVE USR 
SCREEN VAL 

SGN VARPTR- > 
SHARED VARPTR$ 
SHELL VIEW 

SIN WAIT 
SOUND WEND 
SPACE$ WHILE 
SPC( WIDTH 
SOR WINDOW 
STATIC WRITE 
STEP WRITE# 
STICK XOR 
STOP 

STR$ 


Differences Between the Compiler and 
Interpreter 


Differences between the languages supported by the 
BASIC Compiler 2.00 and the BASIC Interpreter must 


BASIC programs. 


be taken into account when compiling existing or new ~ 


To help you become aware of these differences, we 
recommend that you first compile the demonstration 
program in the section called ‘““Sample Session,”’ then 
read the following sections, and only then begin 
compiling your own programs. 


The differences between the languages supported by 
we) the BASIC Compiler 2.00 and the BASIC Interpreter 
are described on the following pages. 


Operational Differences 


Some BASIC commands and statements used to 
operate in the interpreter programming environment are 
not acceptable input to the compiler. These are: 


AUTO LOAD 
CONT MERGE 
bo og eS NEW 
jib) By RENUM 
LIST SAVE 
LLIST 


Certain statements function similarly in the BASIC 
Compiler 2.00 and the interpreter, but require special 
parameters to be specified when used with the 
compiler. 


e Event trapping: If you use any of the event 
trapping statements, you must specify either the /V 
or the /W parameter when you start the compiler. 
The event trapping statements are: 


COM(n) ON STRIG(n) 
KEY(n) ON TIMER 
ON COM(n) PEN STOP 
ON KEY(n) PLAY(n) 


ON PEN STRIG(n) 


YY ON PLAY 


¢ Error trapping: If you use an ON ERROR 
statement and some form of a RESUME 
statement, you must specify either the /E or the 
/X parameter when you start the compiler. If you 
use only the RESUME /Jine form, you should 
specify /E. If you use RESUME NEXT, 
RESUME 0, RESUME, or any combination of 
those with RESUME line, the /X parameter must 
be used instead. 


e Debug code (TRON and TROFF): To use TRON 
and TROFF, the /D parameter must be specified 
when you run the compiler. Otherwise, TRON and 
TROFF are ignored and a warning is generated. 


Note that using these parameters increases the size of 
the .OBJ and .EXE files. See ‘““Compiler Parameters,” 
earlier in this book, for a detailed explanation of each 
of the compiler parameters. 


Language Differences 


If your machine has a cassette port, the BASIC 
Compiler 2.00 supports cassette I/O. However, to 
enable cassette I/O, you must specify the /O 
parameter at compiletime and then link the 
IBMCAS.OBJ module. 


Some differences exist between the following 
commands, statements, and functions of BASIC 
Compiler 2.00 and BASIC Interpreter: 


BEEP COLOR 
BLOAD COMMAND$ 
BSAVE COMMON 
CALL DEF FN 
CALLS END DEF 
CALL ABSOLUTE EXIT DEF 
CHAIN DEFnype 
CHDIR DIM 
CIRCLE DRAW 
CLEAR END 

CLS ENVIRON 


ENVIRON$ 
ERASE 


ON STRIG 
ON TIMER 
OPEN 

OPEN "COM 
PAINT 
PALETTE 


PALETTE USING 


PUT 


WHILE...WEND 
WIDTH 
WINDOW 
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Other Differences 


Other differences between the BASIC Interpreter and 
the BASIC Compiler 2.00 include the following: 


Double-Precision Arithmetic Functions ‘> 


If you use double-precision operands for any of the 
arithmetic functions, including the transcendental 
functions (SIN, COS, TAN, ATN, LOG, EXP, and 
SOR), the BASIC Compiler 2.00 returns 
double-precision results. In the interpreter, 
double-precision results are returned if the interpreter is 
invoked with the /D parameter. 


Double-Precision Loop Control Variables 


The compiler, unlike the interpreter, allows the use of 
double-precision loop control variables. This allows 
you to increase the precision of increment in loops. 


Expression Evaluation 


Mathematical computations have been modified in the 
compiler for improved speed and accuracy, so there 
may be slight differences in the results of 
single-precision or double-precision operations 
compared to the interpreter. 


Also, the BASIC Compiler 2.00 performs optimization, 
if possible, when evaluating expressions. 


During expression evaluation, the BASIC Compiler 
2.00 converts operands of different types to the type of 
the more precise operand. 


QR=J%Z+A!+Q# 


The above expression causes J% to be converted to 
single-precision and added to A!. 


This double-precision result is added to Q#. 


The BASIC Compiler 2.00 is more limited than the 
interpreter in handling numeric overflow. For example, 
when run on the interpreter, the following statements 
yield 40000 for M. 


1%=20000 
J%=20000 
M=1%+Jd% 


That is, J% is added to 1%. Because the number 
exceeds the 32767 limit for integers, the interpreter 
converts the result into a floating-point number. The 
result, 40000, is found and saved as the single-precision 
number M. 


The BASIC Compiler 2.00, however, must make type 
conversion decisions during compilation. It cannot 
defer until actual values are known. Thus, the compiler 
generates code to perform the entire operation in 
integer mode and arithmetic overflow may occur. If the 
/D debug parameter is set, the error is detected. 
Otherwise, an incorrect answer is produced. One 
possible way to avoid this problem is to use 
single-precision numbers instead of integers. 


Besides the above type conversion decisions, the 
compiler performs certain valid optimizing algebraic 
transformations before generating code. For example, 
the following program could produce an incorrect result 
when run: 


[%=20000 
J%=-18000 
K%=20000 
MZ=1%+JI%+K% 


If the compiler actually performs the arithmetic in the 
order shown, no overflow occurs. 


However, if the compiler performs 1%+K% first and 
then adds J%, overflow does occur. The compiler 
follows the rules of operator precedence, and 
parentheses may be used to direct the order of 
evaluation. No other guarantee of evaluation order can 
be made. 


Input Statements 


The compiler limits the number of variables read by an 
INPUT or INPUT # statement to 60. 


Also, if you try to enter more than 32767 characters in 
response to any INPUT or LINE INPUT statement, the 
compiler makes the computer sound a beep. 


Integer Variables 


The BASIC Compiler 2.00 can make optimum use of 
integer variables as loop control variables. To help the 
compiler produce faster and more compact object code, “a 
you should use integer variables as much as possible. 

For example, the following program executes much 

faster by replacing I, the loop control variable, with 1%, 

or by declaring I an integer variable with DEFINT. 


190 FOR I=1 10 10 
110 A(1I)=@ 
120 NEXT I 


Also, it is advantageous to use integer variables to 
compute array subscripts. The generated code is faster 
and more compact. 
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Input Editor 


When you respond to an input statement in a compiled 
program, you do not have all the facilities of the BASIC 
program editor to use. The BASIC Compiler 2.00 does 
not allow you to change lines anywhere on the screen; 
you may only edit the current line. 


The input editor supplied with BASIC Compiler 2.00 
uses a special set of commands to manipulate the text 
on the screen. These commands are different from the 
commands used by the editor in the BASIC Interpreter. 


Input Editor Commands 

All of the editor commands, except Delete, require that 
you press the control key (Ctrl) in combination with 
another key. 

Ctrl-B moves cursor back one word. 

Ctrl-C exits program. 

Ctrl-E erases to the end of the current line. 

Ctrl-F moves cursor forward one word. 


Ctrl-H deletes the character to the left of the 
cursor. 


Ctrl-I inserts spaces from the cursor position up to 
the next tab position (tabs are set every 
eight spaces). If the editor is in replace 
mode, any existing characters will be 
overwritten. 


Ctrl-K moves the cursor to the beginning of the 
line. 


Ctrl-M issues a Carriage return and enters the line. 


Ctrl-N moves the cursor to the end of the line. 
Ctrl-R toggles the editor from insert to replace 
mode. 


Ctrl-T toggles the function key display line on and Aa 


off. 
Ctrl-U erases the entire line. 
Ctrl-] moves the cursor one position to the left. 
Ctrl-\ moves the cursor one position to the right. 
Del deletes the character at the cursor. 


The following special program editor keys are not 
supported by the compiler: 


Ctrl-Home 
Cursor Up 


Cursor Down A 
Ctrl-Break. 


If you try to use any of these keys (with the exception 
of Ctrl-Break) in response to an input statement, the 
computer will sound a two-tone beep. 


Pressing Ctrl-Break in response to an input statement 
returns you to DOS. 


All files are closed and the following message is 
displayed: 


STOP in Line xxx of Module Modulename At Address ---:--- 


Hit any key to return to system 


& When a key is pressed, the DOS screen mode is 
restored. 


Number of Files 


The maximum number of files that can be open 
simultaneously is 15. The default value is 3. To 
increase the number of files open simultaneously you 
must have the following in your CONFIG.SYS file: 


FHLES=x*tx 

Where: 

EX is the number of files you plan to have open 
vy simultaneously, plus 5, which are used by 


DOS. The maximum value for xxx is 20. 


PEEKs and POKEs 


PEEKs and POKEs into the interpreter work area (such 
as DEF SEG: POKE 106,0) are interpreter dependent 
and do not work for compiled BASIC. 


Note: PEEK and POKE for dynamic array 
elements work differently than PEEK and POKE 
for static array elements. See the PEEK and 
POKE statements in BASIC Compiler 2.00 
Language Reference for details. 
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String Length 


Strings can be up to 32767 characters long rather than 
255 characters long. Therefore, any string function 
parameters that identify the location in or length of a 
string (which can have a maximum value of 255 in the 
interpreter) can now range to 32767. 


The internal storage format for the string descriptor 
requires 4 bytes rather than 3 bytes (low byte, high 
byte of the length, followed by low byte, high byte of 
the address). If you use machine language subroutines 
with string arguments, you have to recode the 
subroutine to account for this change. 


String Space Implementation 


To increase the speed of housecleaning, the 
implementation of the string space for the compiler 
differs from its implementation for the interpreter. 
Using PEEK, POKE, VARPTR, or assembly language 
routines to change string descriptors may result in a 
String Space Corrupt error. 


The amount of available string space is 64K bytes. 
Because of the string descriptor size and the number of 
internal variables used by the compiler, however, the 
number of elements in a string array is less than the 
amount available in BASIC Compiler Version 1.00 or 
the BASIC Interpreter. To help maximize the use of 
memory space, you can move numeric data into 
dynamic arrays that have a separate data area. Declare 
string arrays as dynamic and ERASE (reuse) the same 
space whenever possible. In addition, you can use 
MID$ to help prevent fragmentation of string space. 
See the example under ‘“‘MID$ Function and 
Statement” in BASIC Compiler 2.00 Language 
Reference for details. 


Line Length 


The interpreter cannot accept lines greater than 254 
characters in length. In contrast to the interpreter, the 
BASIC Compiler 2.00 accepts physical lines of up to 
32766 characters in length. (A physical line for the 
compiler is one that ends in a carriage return-line feed.) 
However, you can make the compiler accept much 
longer Jogical lines of input by ending the physical lines 
with an underscore character (underscores in quoted 
Strings or remarks do not count). The underscore tells 
the compiler to ignore the following carriage return, so 
all it sees in the carriage return-line feed sequence at 
the end of the line is the line feed character. The line 
feed is the line continuation character understood by 
the compiler. For example, the following two physical 
lines: 


100 INPUT "Values for array A"; A(1),_ 
A(2)-, AC3)5. Al4) yah Ae) AC?) 


are read by the compiler as a single INPUT statement, 
Y which inputs seven values into array A. 


It is impractical to use this technique with the program 
editor in the BASIC Interpreter because each line 
created with the BASIC Interpreter editor must begin 
with a number. In addition, BASIC Compiler 2.00 
source programs that use this technique cannot be 
debugged using the interpreter. 
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Compiler Metacommands 


A special feature of the BASIC Compiler 2.00 that is 
not available with the BASIC Interpreter is the support 
of compiler metacommands. They are called compiler 
metacommands rather than BASIC commands because 
they are not actually a part of the BASIC language; 
rather, they are commands to the compiler. The 
metacommands for the BASIC Compiler 2.00 are: 


$DYNAMIC 
$INCLUDE 
$LINESIZE 
$LIST 
$MODULE 
$OCODE 
$PAGE 
$PAGEIF 
$PAGESIZE 
$SKIP 
$STATIC 
$SUBTITLE 
$TITLE. 


Note the distinctive “‘$”’ prefix on the compiler 
metacommands. 


Metacommands can be used in your source file as part 
of a remark (after the keyword REM or the single 
quote). Because they are imbedded in a remark, the 
metacommands do not cause a syntax error when you 
run your program under the BASIC Interpreter, even 
though the interpreter does not support them. All the 
metacommands are discussed in more detail in BASTC 
Compiler 2.00 Language Reference. 
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Chapter 6. Input and Output (I/O) 
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Introduction 
This chapter contains information on input and output 
(I/O) in BASIC. The following topics are discussed: 
YY ¢ Naming and using files and paths 
« Using I/O devices 
e Tree structured directories 
e Device support 


e Displaying output on the screen. 


Files 


A file is a collection of information that is kept 
somewhere other than in the random access memory of 

\& the computer, for example, on disk. To access the 
information, you must open the file with the OPEN 
statement. Then you can use the file for input or 
output. 


BASIC supports the concept of general device I/O 
files. This means that any type of input/output 
between devices can be treated like I/O to a file. For 
example, you can have I/O between two computers 
that does not involve any type of disk access. 


File Number 


BASIC performs I/O operations using a file number. 
You assign the number to a file or device when you 


we open it with the OPEN statement. See ‘““OPEN 
Statement”? in BASIC Compiler 2.00 Language 
Reference. 
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A file number can be any number, variable, or 
expression ranging from 1 to 255. See ‘“‘Number of 
Files” earlier in this section for more information. 


Filename 


For disk files, the name must conform to DOS ‘> 
conventions: 


e The name can consist of two parts separated by a 
period (.). The filename format is: 


name |.extension | 


The name can be from one to eight characters. 
The extension can be from one to three characters. 


If more than three characters are entered for 
extension, the extra characters are truncated. If 
name is longer than eight characters and extension 
is not included, BASIC inserts a period after the 
eighth character and uses the extra characters (up 
to three) for the extension. If name is longer than 
eight characters and an extension is included, an 
error OCCUrS. 


« The following characters are allowed in name and 
extension: 


A through Z 
0 through 9 


$8 Bie see 
#8 5 A & 


Note: Previous releases of BASIC allowed the 
characters <, >, and \ to be used within a 
filename, but these characters now have special 
meaning to BASIC, and can no longer be used in 
filenames. 


Examples of valid filenames: 


27HAL.DAD 
VDL 
PROGRAM 1.BAS 
$$@(!).123 


The following examples show how BASIC shortens 
names and extensions when they are too long. 


A23456789JKLMN becomes: A2345678.9JK 
@HOME.TRUMI10_ becomes: @HOME.TRU 
HENRYOLOVE.BAS causes an error. 


File Specification 


The file is described by its file specification, or filespec 
for short. The file specification is a string expression in 
the form: 


Y | device || path | filename 


The device name tells BASIC which I/O device is being 
used. The path tells BASIC which directory contains 
the file. The filename tells BASIC which file to look for 
on that particular device. Sometimes you do not need 
both device name and path, so specification of device 
and path is optional. 


All device names end with a colon (:). The colon is 
part of the device name and must be included whenever 
a device is specified. 


Note: File specifications for communications 
devices are different. The filename is replaced 
with a list of options specifying such things as line 
speed. See ““OPEN “‘COM ... Statement”’ in 

& BASIC Compiler 2.00 Language Reference for 
details. 
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If you use a string constant for the filespec, you must 
enclose it in quotation marks. For example: 


FILES “B:PROG.BAS" 
You can specify a path to a file in your filespec. 


A path is a list of directory names separated by ‘> 
backslashes (\). If you specify a file that is not in the 

current directory, you must supply the compiler with a 

path of directory names so it can locate the file. 


You can use paths for the following commands: 


BLOAD MKDIR 
BSAVE NAME 
CHAIN OPEN 
CHDIR RMDIR 
FILES RUN 
KILL 


Notes: 


1. A path cannot contain more than 63 characters. “a 
2. If you specify a device, place the device name 


before the path. If you place it anywhere else, you 
receive a Bad filename error message. 


3. If you use a string constant for the path, you must 
enclose it in quotation marks. For example: 


"B: \SALES \ JUNE \ REPORT \ " 


Devices 


Device Names 


When you start the BASIC Compiler 2.00, you must 
give file specifications for the files it needs. In all cases 
the default device for the files is the DOS default 
diskette drive; you can override the default by including 
the device name as part of the filespec. 


A device name consists of up to four alphanumeric 
characters followed by a colon (:). It is a name 
assigned to input/output devices for the IBM Personal 
Computer. 


The device name for the source file indicates the device 
the file is read from. Allowable devices are: 


Y Keyboard/Screen/Printer Devices 


CON: Keyboard (Buffered input) or Screen 
(Buffered output). 

USER: Keyboard (Nonbuffered input) or 
Screen (Nonbuffered output). 

KYBD: Keyboard. Input only. 

SCRN: Screen. Output only. 

LPT 1: First printer. Output or random 
access. 
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LPT2: Second printer. Output or random 


access. 
LPT3: Third printer. Output or random 
access. 
Communications Devices (> 
COMI: First Asynchronous Communications 


Adapter. Input and output. 


COM?: Second Asynchronous 
Communications Adapter. Input and 
output. 

AUX: Auxiliary Asynchronous 


Communications Adapter. 


NUL: No output. 


Storage Devices 


CASI: Cassette drive. Input and output. 
A:, B:, C:, etc. Disk Drives. Input and output. 


CON is a DOS reserved word for the display device. 
Output written to CON is buffered as a file and thus 
appears in the display in blocks of 512 characters at a 
time. 


USER is a special reserved word for the display. 
Output written to USER is not buffered and thus 
appears on the screen on a character-by-character 
basis. 


An object file sent to the screen or printer is unreadable 
because it consists of binary code. 


Device Support 


BASIC’s file I/O system allows the use of user-installed 
devices. (See the DOS Technical Reference manual for 
information on device drivers. ) 


You could, for instance, write your own device driver to 
replace LPT1:. Your program would open this driver as 
follows: 


OPEN "LPT1" FOR mode AS #filenum 


Several rules must be followed when writing a device 
driver. 


« The name of the installed device cannot end with a 
colon. Device names ending with a colon are 
reserved for certain predefined devices (KYBD:, 
SCRN;, etc.). 


e LPT1:, LPT2:, and LPT3: are the only system 
device drivers that can be replaced by an installed 
device driver having the same name. 


e The record length is set to 1 unless changed by the 
OPEN statement: 


OPEN device FOR mode AS #filenum LEN=recl 
When this option is used, BASIC buffers the 
number of characters equal to record length before 
sending them to the driver. 

e BASIC sends only a carriage return (&HOD) at the 


end of a line. If a line feed (&HOA) is needed, the 
driver must provide it. 
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¢ Your device driver must be able to return an End 
of file condition to BASIC if you want to close a 
sequential input file open to a device driver. If 
BASIC attempts to read past the end of the device 
input stream, the driver should return a AZ 
(Control-Z), which is used by BASIC as an 


end-of-file mark. ‘> 
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Directories 


Types of Directories 


we) A single directory is created on each disk or diskette 
when you use the DOS FORMAT command. That 
directory is called the root directory. The maximum 
number of files in a diskette root directory depends on 
the medium being used. The maximum number of files 
in a fixed disk root directory depends on the size of the 
DOS partition on the disk. 


In addition to containing the names of files, the root 
directory also contains the names of other directories 
called subdirectories. Unlike the root directory, these 
subdirectories are actually files. Subdirectories can 
contain any number of files and subdirectories and are 
limited only by the amount of available space on the 
diskette or disk. 


YY Subdirectory names are in the same format as 
filenames. All characters that are valid for filenames 
are valid for subdirectory names. Each subdirectory 
can contain file and directory names that also appear in 
other directories. 


Current Directory 


Just as BASIC remembers a default drive, it can also 
remember a default directory for each drive on your 
system. This is called the current directory and is the 
directory that BASIC searches if you enter a filename 
without telling BASIC which directory contains the file. 
You can change the current directory by issuing the 
CHDIR command. See ‘““CHDIR Command,”’ 

wy “MKDIR Command,” and ‘‘RMDIR Command” in 
BASIC Compiler 2.00 Language Reference. 
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If a filename is included in a path, it must be separated 
from the previous directory name by a backslash (\). 
If a path begins with a backslash, BASIC starts its 
search from the root directory; otherwise, the search 
begins at the current directory. 


Tree-Structured Directories ‘> 


BASIC Compiler Version 1.00 uses a simple directory 
structure for managing files on diskettes. With the 
added hardware support for fixed disks and high density 
diskettes, a more sophisticated method is needed to 
manage the thousands of files that a single fixed disk 
can hold. 


You can better organize and manage your disks by 
placing groups of related files in their own directories 
on the same disk. These directories are known as 
tree-structured directories. These directories begin with 
the root directory and branch into subdirectories. 


For example, if a company has two departments, DOS 
and LANG, that share an IBM Personal Computer, all ~ 
the company’s files can be kept on the computer’s fixed 

disk. The organization of the files might look like this: 


ROOT 
DOS LANG 
e 
DOS21 DOS30 BASIC FORTRAN PASCAL 
INT COMPILER 


BASIC Disk Input and Output 


This section describes procedures and special 

considerations for using disk input and output. It 

contains lists of the commands and statements that are 

used with disk files, and explanations of how to use 
‘oe them. Several sample programs are included to help 
clarify the use of data files on disk. If you are new to 
BASIC or if you’re getting disk-related errors, read 
through these procedures and program examples to 
make sure you are using all the disk statements 
correctly. 


You may also want to refer to the IBM Personal 
Computer Disk Operating System (DOS manual) for 
other information on handling disks and disk files. 


Specifying Filenames 


Filenames for disk files must conform to DOS naming 
conventions for BASIC to be able to read them. See 

YY the “‘Files”’ section of this chapter to be sure you are 
specifying your disk files correctly. 


Disk Data Files—Sequential and Random I/O 


Two types of disk data files can be created and 
accessed by a BASIC program: sequential files and 
random access files. 


Sequential Files 


Sequential files are easier to create than random files, 
but are limited in flexibility and speed when accessing 
data. The data that is written to a sequential file is 
stored sequentially, one item after another, in the order 
that it is sent. Each item is read back in the same way, 
from the first item in the file to the last item. 


The statements and functions used with sequential files 
are: 


CLOSE LOF 

EOF OPEN 

INPUT # PRINT # 
INPUT$ PRINT # USING 
LINE INPUT # WRITE # 

LOC 


Creating and Accessing a Sequential File 


To create a sequential file and access the data in it, 
include the following steps in your program: 


1. Open the file for output or append using the 
OPEN statement. 


2. Write data to the file using the PRINT #, WRITE 
#, or PRINT # USING statements. 


3. To access the data in the file, you must close the 
file (using CLOSE) and reopen it for input (using 
OPEN). 


4. Use the INPUT # or LINE INPUT # statements to 
read data from the sequential file into the program. 


These steps are shown in PROGRAM 1. 


19 REM PROGRAM1 - SEQUENTIAL FILES 


20 OPEN "DATA" FOR OUTPUT AS #1 SOLEP A 
38 FOR I=1 TO 190 

40 PRINT #1,1 ig j= ae 
5Q@ NEXT 

609 CLOSE eo tS ae 


7@ OPEN "I" ,#1,"DATA" 

8@ IF EOF(1) THEN CLOSE:END 

99 INPUT #1,A ‘STEP 4 
19% PRINT A 

11% GOTO 8@ 


Notice the two ways of writing the OPEN statement in 
line 20 and line 70. See ““OPEN Statement” in BASIC 
Compiler 2.00 Language Reference for details on the 
syntax of each form of OPEN. 


In line 80 the EOF function tests for end of file. This 
prevents an Input past end error. The end of file is 
indicated by a special character in the file. This 
character has ASCII code 26 (hex 1A). Therefore, you 
should not put a CHR$(26) in a sequential file. 


A program that creates a sequential file can also write 
formatted data to the disk with the PRINT # USING 
statement. For example, the statement: 


PRINT #1,USING "####.## "3A,B,C,D 
can be used to write numeric data to disk without 


explicit delimiters. The space at the end of the format 
string separates the items in the disk file. 
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The LOC function, when used with a sequential file, 
returns the number of records that have been written to 
or read from the file since it was opened. (A record is a 
128-byte block of data.) 


The LOF function returns the number of bytes 
allocated to the file. 


Adding Data to a Sequential File 


To add data to a sequential file residing on disk, you 
cannot simply open the file for output and start writing 
data. When you open a sequential file for output, you 
destroy its current contents. Instead, you should open 
the file for APPEND. See ‘““OPEN Statement” in 
BASIC Compiler 2.00 Language Reference for details. 


Random Files 


Creating and accessing random files require more 
program steps than sequential files, but there are 
advantages to using random files. For instance, 
numbers in random files are usually stored on disk in 
binary formats, while numbers in sequential files are 
stored as ASCII characters. Therefore, in many cases 
random files require less space on disk than sequential 
files. 


The biggest advantage to random files is that data can 
be accessed randomly; that is, data can be accessed 
anywhere on the disk. It is not necessary to read 
through all the information, as with sequential files. 
This is possible because the information is stored and 
accessed in distinct units called records, and each 
record is numbered. 


Records can be any length up to 32767 bytes. The size 
of a record is not related to the size of a sector on the 
disk (512 bytes). 


BASIC automatically uses all 512 bytes in a sector for 
information storage. It does this by both blocking 
records and spanning sector boundaries; that is, part of 
a record can be at the end of one sector and the other 
part at the beginning of the next sector. 


The statements and functions used with random files 


are: 
CLOSE CVS 
FIELD LOC 
GET LOF 
LSET/RSET MKD$ 
OPEN MKI$ 
PUT MKS$ 
CVD 
CVI 


Creating a Random File 


The following program steps are required to create a 


vw random file: 


1. Open the file for random access. The example that 
follows specifies a record length of 32 bytes. If the 
record length is omitted, the default is 128 bytes. 


2. Use the FIELD statement to allocate space in the 
random buffer for the variables that are written to 
the random file. 


3. Use LSET or RSET to move the data into the 
random buffer. Numeric values must be made into 
strings when placed in the buffer. To do this, use 
the ‘‘make’’ functions: MKI$ to make an integer 
value into a string, MKS$ for a single-precision 
value, and MKD$ for a double-precision value. 


4. Write the data from the buffer to the disk using the 
PUT statement. 


These steps are shown in PROGRAM2. 


Note: Do not use a string variable that has been 

defined in a FIELD statement in an input 

statement or on the left side of an assignment (> 
(LET) statement. This causes the pointer for that 

variable to point into string space instead of the 

random file buffer. 


Look at PROGRAM2. It writes to a random file the 
information entered at the keyboard. Each time the 
PUT statement is executed, a record is written to the 
file. The two-digit code that is input in line 30 becomes 
the record number. 


1@ REM PROGRAM2 - CREATE A RANDOM FILE 

20 OPEN "DATAY" AS #1 LEN=32 “STEP 4 
30 FIELD #1,20 AS N$, 4 AS A$, 8 AS P$ Sees 
49 INPUT "2-DIGIT CODE" ;CODE% 

5@ IF CODE%=99 THEN CLOSE: END 


6@ INPUT "NAME" ;X$ 

7@ INPUT "AMOUNT" ; AMT “~ 
80 INPUT "PHONE";TEL$: PRINT 

99 LSET N$=X$ Stee 

19@ LSET A$=MKS$(AMT ) ‘STEPS 

110 LSET P$=TEL$ “STEPS 

120 PUT #1,CODE% "Stee = 

139 GOTO 40 


Accessing a Random File 


The following program steps are required to access a 
random file: 


1. Open the file for random access. 
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2. Use the FIELD statement to allocate space in the 
random buffer for the variables that are read from 
the file. 


Note: In a program that performs both input 

and output on the same random file, you can 

usually use just one OPEN statement and one 
FIELD statement. 


3. Use the GET statement to move the desired record 
into the random buffer. 


4. The data in the buffer can now be accessed by the 
program. Numeric values must be converted back 
to numbers using the “‘convert’”’ functions: CVI for 
integers, CVS for single-precision values, and 
CVD for double-precision values. 


These steps are shown in PROGRAMS. 
PROGRAMS accesses the random file that was created 


in PROGRAM2. When the two-digit code is entered at 
the keyboard, the information associated with that code 


YY is read from the file and displayed. 
1@ REM PROGRAM3 - ACCESS A RANDOM FILE 
20 OPEN "DATAY" AS #1 LEN=32 ‘STEP-1 
30 FIELD #1,2@ AS N$, 4 AS A$, 8 AS P$ ‘STEP 2 


49 INPUT "2-DIGIT CODE" ;CODE% 
5@ IF CODE%=99 THEN CLOSE: END 


60 GET #1, CODE% STEPS 
7Q@ PRINT N$ ‘STEP 4 
80 PRINT USING "$$###.##" 5CVS(A$) ‘STEP 4 
99 PRINT P$ 
199 GOTO 49 


With random files, the LOC function returns the 
current record number. The current record number is 
the latest one used in a GET or PUT statement. For 
example, the statement: 


w IF LOC(1)>5@ THEN END 
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ends program execution if the current record number in 
file #1 is higher than 50. 


Screen Displays 


BASIC can display text, special characters, points, %y 
lines, and more complex shapes in one color or in full 

color. How much of this you can do depends on which 

display adapter you have in your IBM Personal 

Computer. 


Display Adapters 


The IBM Monochrome Display and Printer Adapter, 
and the Color/Graphics Adapter are two display 
adapters available for the IBM Personal Computer. 


With the monochrome adapter, text is displayed in one 
color. Text refers to letters, numbers, and all the 
special characters. You have some capability to draw 

pictures with the special line and block characters. You “~ 
can also create blinking, reverse image, invisible, 

highlighted, and underscored characters by setting 

parameters in the COLOR statement. 


The Color/Graphics Adapter also operates in text 
mode, but it allows you to display text in up to 16 
colors by assigning different values to the COLOR 
statement. This adapter also provides you with special 
modes that allow you to draw complex pictures on the 
screen. This graphics capability makes the screen all 
points addressable in medium and high resolution. This 
is more versatile than the ability to draw with the 
special line and block characters that you have in text 
mode. In this book and in the BASIC Compiler 2.00 
Language Reference, the term graphics refers only to 
this special capability of the Color/Graphics Adapter. 
The use of the extended character set with special line 
and block characters is not considered graphics. 
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Text Mode 


The screen can be pictured like this: 


Character 
position 1, 1 


Border 
screen 


Characters are shown in 25 horizontal lines across the 
screen. Line 1 is at the top, line 25 at the bottom. 
Each line has 40 character positions (or 80, depending 
on how you set the width). These are numbered | to 
40 (or 80) from left to right. 


The position numbers are used in the LOCATE 
statement, and are the values returned by the POS(0) 
and CSRLIN functions. For example, the character in 
the upper left corner of the screen is on line 1, position 
a. 


Characters are normally placed on the screen through 
the use of the PRINT statement. Characters are 
displayed at the position of the cursor from left to right 
on each line, from line 1 to line 24. When the cursor 
would normally go to line 25 on the screen, lines 1 
through 24 are scrolled up one line, so that what was 
line 1 disappears from the screen. Line 24 is then 
blank, and the cursor remains on line 24 to continue 
vy printing. 
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Line 25 is usually used for “‘soft key’”’ (function key) 
display (see ““KEY Statement” in BASIC Compiler 
2.00 Language Reference), but you can write over this 
area of the screen if you turn off the function key 
display, and use the LOCATE statement to position the 
cursor at line 25. The 25th line is never scrolled by 


BASIC. a) 


Each character on the screen is composed of two parts: 
foreground and background. The foreground is the 
character itself. The background is the “‘box’’ around 
the character. You can set the foreground and the 
background color for each character by using the 
COLOR statement. You can also make characters 
blink. 


You can use a total of 16 different colors if you have 
the Color/Graphics Monitor Adapter: 


0 Black 8 Gray 

1 Blue 9 Light Blue 

2 Green 10 Light Green 

3 Cyan 11 Light Cyan 

4 Red 12 Light Red 

5 Magenta 13 Light Magenta 

6 Brown 14 Yellow 

7 White 15 High-intensity White 


Colors may vary depending on your display device. 
Colors 8—15 are high-intensity values of colors 0-7. 


Most television sets or monitors have an area of 
overscan that is outside the area used for characters. 
This overscan area is known as the border screen. You 
can use the COLOR statement to set the color of the 
border screen. 
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Statements you can use to display information in text 
mode are: 


CLs SCREEN 
COLOR WIDTH 
LOCATE WRITE 
PRINT 


The following functions and system variables can be 
used in text mode: 


CSRLIN SPC 
POS TAB 
SCREEN 


Another special feature you get in text mode if you 
have the Color/Graphics Adapter is multiple display 
pages. The Color/Graphics Adapter has a 16K-byte 
screen buffer, but text mode needs only 2K bytes of 
that (or 4K bytes for 80-column width). So the buffer 
is divided into pages, which can be written on and/or 
displayed individually. There are eight pages, 

YY numbered O to 7, in 40-column width, and four pages, 
numbered O to 3, in 80-column width. 


See “SCREEN Statement” in BASIC Compiler 2.00 
Language Reference. 
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Graphics Modes 


The graphics modes are available only if you have the 
Color/Graphics Monitor Adapter. 


You can use BASIC statements to draw in the following 
graphics resolutions: 


e medium resolution — 320 by 200 points and four 


colors 


e high resolution — 640 by 200 points and two colors 


You can select the resolution you want to use with the 
SCREEN statement. The BASIC statements used for 


graphics are: 


CIRCLE 
COLOR 
DRAW 
GET 


LINE 
PAINT 
POINT 
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PRESET 
PSET 
PUT 
SCREEN 


VIEW 
PMAP 
WINDOW 


Color Attributes 


There is a numeric value that describes the color of 
each point on the screen. This numeric value is called 
an attribute. For example, if you refer to the list of 
available colors in “COLOR Statement (Text Mode)”’ 
in BASIC Compiler 2.00 Language Reference, you can 
see that the color blue is indexed by the attribute 1. 


The color for attribute varies depending on the current 
screen mode. The variance is based on the attribute 

range for each mode. The maximum attribute for each 
mode determines how many bits are required to define 
the attribute for a point—the number of bits per pixel. 


ew Consider the attribute range for SCREEN 1, which is 
O-3. In binary, 2 bits are required to represent a 
decimal number as large as 3. For a screen mode with 
an attribute range of 0-1, only 1 bit is needed to 
represent these values. Mathematically, the number of 
bits per pixel is equal to the log base 2 of the maximum 
attribute available for that screen mode. This concept 
is particularly important when using the paint tiling 
feature. See ‘““PAINT Statement” in BASIC Compiler 
2.00 Language Reference for more information. 
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Low Resolution 


Medium Resolution 


There are 320 horizontal and 200 vertical points in 
medium resolution. Points are numbered from left to 
right, top to bottom, starting with zero. The upper left 
corner of the screen is point 0,0; the lower right corner 
is point 319,199. The numbering method is just the 
opposite of the usual mathematical method for 


numbering coordinates. Medium resolution is set by a 
SCREEN 1 statement. 


Medium resolution is unusual because of its color 
characteristics. When you put something on the screen 
in medium resolution, you can specify a color attribute 
number of 0, 1, 2, or 3. The colors for these attributes 
are not fixed, as are the 16 colors in text mode. You 
can select 1 of 16 colors for the background and one of 
two palettes of color for the foreground. Then you 
select one of two “‘palettes’’ for the other three 
attributes by using the COLOR statement. A palette is 
a set of three colors to be associated with attributes 1, 
2, and 3. If you change the palette with a COLOR 
statement, all the colors on the screen change to match 
the new palette. 


You can still display text characters on the screen when 
you are in graphics mode. The size of the character 
display area is the same as in text mode, that is, 25 lines 
of 40 characters. In medium resolution, the default 
foreground is attribute 3, and the default background is 
attribute O. 
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High Resolution 


In high resolution, there are 640 horizontal and 200 
vertical points. As in medium resolution, points are 
numbered starting with zero with the lower right corner 
point being 639,199. High resolution is set by the 
SCREEN 2 statement. 


High resolution has only two colors: black and white. 
Black is always O (zero), and white is always 1 (one). 


When you display text characters in high resolution, 
you get 80 characters per line. The foreground color is 
1, and the background color is 0. Characters are always 
white on black. 


Assigning Colors to Attributes 
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Specifying Coordinates 


The graphic statements require information about 
where on the screen you want to draw. You give this 
information in the form of coordinates. Coordinates 
are generally in the form (x,y), where x is the horizontal 
position, and y is the vertical position. This form is 
known as absolute form and refers to the actual 
coordinates of the point on the screen, without regard 
to the last point referenced. 


There is another way to show coordinates, known as 
relative form. Using this form you tell BASIC where the 
point is, relative to the last point referenced. This form 
looks like: 


STEP (xoffset, yvoffset) 


You indicate inside the parentheses the offset in the 
horizontal and vertical directions from the last point 
referenced. 


Initially, (after SCREEN 1, SCREEN 2, WIDTH or 


CLS) the “‘last point referenced”’ is the point in the 
middle of the screen; that is (160,100) for medium 
resolution, or (320,100) for high resolution. 


6-29 


Later statements change the last point referenced. ‘> 
What each graphics statement sets as the last point 

referenced is indicated in the discussion of that 

statement in BASIC Compiler 2.00 Language 

Reference. © 


Note: Unlike BASIC Compiler Version 1.00, 
images defined with coordinates that are out of 
range are clipped so that only points plotted within 
the boundaries of the window are visible. 


This example shows the use of both forms of 
coordinates: 


190 SCREEN 1 
110 PSET (200,100) ‘absolute form 
120 PSET STEP (10,-20) ‘relative form 


This sets two points on the screen. Their actual 
coordinates are (200,100) and (210,80). 


World Coordinates and Device Coordinates 


The VIEW and WINDOW statements use the concept 
of world coordinates and device coordinates. The world 
coordinate system allows you to define the dimensions 
of an image without regard for the physical size of the 
display device. When you display the image, device 
coordinates are used to scale the image to suit the 
actual dimensions of the display device. 
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Chapter 7. Data Types 
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Introduction 


The data that your program uses can be classified into 
several types. This chapter explains the different types 
of data that BASIC uses. 


we This chapter includes a discussion of: 


« Numbers 

e Strings 

e Arrays 

« Constants 

« Variables 

e Numeric precision 

“ Numeric conversion. 


Numbers 


Numeric data can be represented as constants or 
variables. If numeric data is represented using 
variables, you can also specify the precision, or number 
of decimal places, that you need. 


Numeric Constants 


Numeric constants are positive or negative numbers. A 
plus sign (+) is optional on a positive number. 
Negative numbers must be signed. Numeric constants 

\& in BASIC cannot contain commas. There are five ways 
to indicate numeric constants: 
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Integer 


Fixed-point 


Floating-point 


Whole numbers between —32768 and 
+32767, inclusive. Integer constants 
do not have decimal points. 


Positive or negative real numbers, 
that is, numbers that contain decimal 
points. 


Positive or negative numbers 
represented in exponential form 
(similar to scientific notation). In 
single-precision calculation, a 
floating-point constant consists of an 
optionally signed integer or 
fixed-point number (the mantissa) 
followed by the letter E and an 
optionally signed integer (the 
exponent). Double-precision 
floating-point constants use the 
letter D instead of E. The E (or D) 
means “times ten to the power of.”’ 


You can represent any number from 
2.9E-39 to 1.7E+38 (positive or 
negative) as a floating-point 
constant. 


Examples: 
go | a 


Here, 23 is the mantissa, and —2 is 
the exponent. This number could be 
read as ‘‘23 times 10 to the negative 
two power.”’ You could write it as 
0.23 in regular fixed-point notation. 


235. 988&-7 


This is a single-precision number 
equivalent to .0000235988. 


2359D6 


This is a double-precision number 
equivalent to 2359000000. 


Remember, when you read 
floating-point notation: E indicates 
single-precision calculation and D 
indicates double-precision 
calculation. 


For more information, see ‘‘Numeric 
Precision”’ later in this chapter. 


Hex Hexadecimal integer numbers up to 
four digits, with a prefix of &H. 
Hexadecimal digits are the numbers 
0 through 9, A, B, C, D, E, and F. 


Examples: 
&H76 
Y& &H32F 


Octal Octal integer numbers up to six 
digits, with the prefix &O or just &. 
Octal digits are O through 7. 
Examples: 


&0347 
&1234 


Numeric Variables 


Variables are names used to represent values in a 
BASIC program. A numeric variable always has a 
number value. 


You can give a variable an unchanging value (such as 
salary equals a certain amount) or you can set its value 
to be the result of calculations or data input statements 
in the program (such as salary equals 10% of sales). In 
any case, the variable type (string or numeric) must 
match the type of data assigned to it. 


If you use a numeric variable before you assign a value ‘> 
to it, its value is assumed to be zero. 


How to Name a Numeric Variable 


BASIC allows a variable name to be up to 40 
characters. 


The characters can be letters, numbers, and decimal 
points. The first character must be a letter. Special 
characters that identify the type of variable are also 
allowed as the last character of the name. For more 
information about types, see the next section, “‘How to 
Declare Numeric Variable Types.”’ 


A variable name cannot be a reserved word, but it can 
contain imbedded reserved words. For example: 


10 EXP = 5 

is invalid, because EXP is a reserved word. However, 
1Q EXPONENT = 5 

is okay, because EXP is vhbodder in the variable name. 
For more information and a complete list of reserved 


words, see the ‘‘Reserved Words”’ section and the /4 
parameter in the ‘“Compiler Parameters”’ section. 
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Note: Do not begin a variable name with FN 
unless you intend to call a user-defined function. 
See ‘“‘DEF FN Statement” in BASIC Compiler 
2.00 Language Reference. 


How to Declare Numeric Variable Types 


A variable name determines its type (string or numeric 
and, if numeric, its precision). 


Numeric Precision 


Numbers can be stored internally as integer, 
single-precision, or double-precision numbers. 
Constants entered in integer, hex, or octal format are 
stored in 2 bytes of memory and are interpreted as 
integers (whole numbers). With double-precision 
calculation, the numbers are stored with 17 digits of 
precision and printed with up to 16 digits. With 
single-precision calculation, seven digits are stored and 
up to seven digits are printed, although only six digits 
may be accurate. Seven digits are printed in 
single-precision because any intermediary processing 
uses all seven digits. To ensure the accuracy of final 
results, enter all seven digits before the final results 
when you do interactive processing. 


Numeric variable names can declare integer, 
single-precision, or double-precision values. Although 
computations with single-precision variables are less 
accurate, there are advantages to using them: 


e They require less storage. 


e They can be calculated faster. 
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The type-declaration characters for numeric variables 
and the number of bytes required to store each type of 
value are: 


% Integer variable (2 bytes) 


! Single-precision variable (4 bytes) “> 
# Double-precision variable (8 bytes). 


Note: If the type-declaration character is not 
specified, the default is single-precision. 


Examples of variable names with type-declaration 
characters are: 


PI# declares a double-precision value 
MINIMUM! declares a single-precision value 
LIMIT% declares an integer value 

N$ declares a string value 

ABC defaults to a single-precision value 


Variable types can also be declared in other ways. The 
BASIC statements DEFINT, DEFSNG, DEFDBL, and 
DEFSTR can be included in a program to declare the 
types for certain variable names. These statements are 
described under ““‘DEFtype Statements” in the BASIC 
Compiler 2.00 Language Reference. All of the examples 
in this book assume that no DEFtype statements were 
used (unless they are explicitly shown in the examples). 


In summary, the following general rules apply: 


A single-precision constant is any numeric constant 
written with any one of the following: 


e seven or fewer digits 


e exponential form using E 


¢« trailing exclamation point (!). 
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A double-precision constant is any numeric constant 
written with any one of the following: 


e eight or more digits 

e exponential form using D 

¢« trailing number sign (#). 

The following table summarizes the precision and range 


of integers, single-precision numbers, and 
double-precision numbers: 


TYPE RANGE ACCURACY 
Integer —32768 to 32767 ~~=Perfect 
Single-precision 10E-38 to 6 decimal 
floating-point 10E+38 digits 
Double-precision 10D-—38 to 16 decimal 
floating-point 10D+38 digits 


Examples of single-precision and double-precision 
constants: 


Single-Precision Double-Precision 
46.8 345692811 
—1.09E-—06 —1.09432D—-06 
3489.0 3489.0# 

22: 7654321.1234 
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How BASIC Converts Numbers from One 
Precision to Another 


When necessary, BASIC converts a number from one 

precision to another. If a numeric value of one precision 

is assigned to a numeric variable of a different 

precision, the number is stored as the precision declared (> 
in the target variable name. 


Example: 


19 A% = 23.42 
20 PRINT AZ 


Result: 
23 


Rounding up, as opposed to truncation, occurs when 
assigning any higher precision value to a lower precision 
variable (for example, changing from double-precision 
to single-precision values). 


Example: A 


19 C = 55.8834567# 
20: -PRINTCC 


Result: 
55 .88346 


This affects not only assignment statements (for 
example, 1% =2.5 results in 1% =3), but also function 
and statement evaluations. For instance, TAB(4.5) 
goes to the fifth position; A(1.5) is the same as A(2); 
and X=11.5 MOD 4 results in a value of O for X. 


If you convert from a lower precision to a higher 
precision number, the resulting higher precision number 
cannot be any more accurate than the lower precision 
number. 
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For example, if you assign a single-precision value (A) 
to a double-precision variable (B#), only the first six 
digits of B# will be accurate because only six digits of 
accuracy were supplied with A. The error can be 
bounded using the following formula: 


ABS(B#-A) < 6.3E-8 * A 


That is, the absolute value of the difference between 
the printed double-precision number and the original 
single-precision value is less than 6.3E—8 times the 
original single-precision value. 


Example: 
10 A = 2.04 
20 BH =A 


30 PRINT A;B# 
Results: 
2.94 2.039999961853027 


When an expression is evaluated, all the operands in an 
arithmetic or relational operation are converted to the 
same degree of precision, namely the most precise 
operand. Also, the result of an arithmetic operation is 
returned to this degree of precision. 


Examples: 


10 D# = 6#/7 
20 PRINT D# 


Result: 


.8571428571428571 


The arithmetic is performed in double-precision and the 
result is returned in D# as a double-precision value. 


10 D = 6#/7 
20 PRINT D 
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Result: 
.8571429 


The arithmetic is performed in double-precision and the 
result is returned to D (single-precision variable), 
rounded, and printed as a single-precision value. 


Logical operators (see ‘‘Logical Operators” in the 
following chapter) convert their operands to integers 
and return an integer result. Operands must be in the 
range —32768 to 32767 or an Overflow error occurs. 


Techniques for Formatting Numeric Output 
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BASIC has built-in statements and functions that you 
can use in your programs to display numbers in the 
desired format and with the desired accuracy. 


« Use DEFDBL to define your constants and 


variables as double-precision numbers to format 
your output. 


For example: 


10 WIDTH 8@ 

20 DEFDBL A 

30 A=70# 

49 PRINT A/1Q00#4, 

50 A=At+1 

60 IF A<1@Q0# GOTO 4@ 

Results: 
< me? | Oy hd ioe 74 
.75 v6 ee a .78 .79 
.8 .81 {82 .83 . 84 
.85 . 86 387 . 88 .89 
9 .91 .92 .93 .94 
95 .96 .97 .98 .99 


« When you want your program results displayed in 
decimal notation, use the PRINT USING and 
LPRINT USING statements. These statements let 
you choose the format in which the results are 
printed or displayed. For example: 


10 FOR I=4 tesbegre 22 
20 PRINT USING "#.#'°51; 
30 NEXT 


Results: 


4 Oo SAsd 452. 4.3 eee. 7 A 49 8 


Notes: 


1. Avoid using both single-precision and 
double-precision numbers in the same formula 
because it reduces accuracy. 


2. Use double-precision transcendental functions for 
greater accuracy. 


Strings 


Data that consists of mainly alphabetic characters is 
represented by a form called a string. As the name 
implies, this is just a series of characters strung 
together. A string may contain numbers, but cannot be 
used in mathematical calculations. 


String Constants 


Constants are values that you supply when you write a 
BASIC program and do not change during program 


Y execution. 


A string constant is a sequence of up to 32767 
characters enclosed in double quotation marks. The 
characters can be letters, numbers, or symbols. 
Examples of string constants are: 


"HELLO" 
"$25 090.00" 


“Number of Employees" ‘> 


There are a few cases where the compiler knows that a 
particular thing must be a string constant, and the 
quotation marks are not required. These cases are 
noted where appropriate in this book. Also, if you start 
a string with a quotation mark, but forget to add the 
end quotation mark, the compiler assumes that a 
quotation mark is at the end of the line. Of course, this 
produces correct results only if a string constant is the 
last thing on the line. 


String Variables 


Variables are names used to represent values in a 
program. A string variable can have up to 32767 
characters. ~ 


You can give a string variable an unchanging value 
(such as Name$=‘“‘Glenn A. Crumpley’’) or you can set 
its value to be the result of calculations or data input 
statements in the program (such as Name$=A$). In 
any case, the variable type (string or numeric) must 
match the type of data assigned to it. String variables 
are initially assumed to be null; that is, they have no 
characters in them and have a length of zero. 


BASIC allows a variable name to be up to 40 characters 
in length. The characters can be letters, numbers, and 
decimal points. The first character must be a letter, and 
the last character must be a dollar sign ($). 


For example: 
A$ = "SALES REPORT" 


The dollar sign is a variable type-declaration character. 
It ‘‘declares’’ that the variable represents a string. 


Arrays 


An array is a list or table of values that is referred to by 
a single name. Each value in the array is called an 
element. Elements are string or numeric variables and 
can be used in expressions and in BASIC statements. 


The subscript (the number in parentheses) indicates the 
position of an element in an array. Zero is the first 
position unless you explicitly change it. See “OPTION 
BASE Statement” in BASIC Compiler 2.00 Language 
Reference. 


number of elements and their arrangement within it is 
known as defining, or dimensioning, the array. The 
maximum number of dimensions for an array is 255. 


YY Declaring the name and type of an array and setting the 


If you use an array element before you define 
(dimension) the array, it is assumed to be dimensioned 
with a maximum subscript of 10. That is, only the first 
eleven elements (indexed 0 to 10) are recognized. 


To define an array, use the DIM statement. For 
example: 


DIM B$(5) 


This statement creates a one-dimensional, 
string-variable array named B$ with a maximum of 6 


YY elements. 
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Array B$ can be thought of as a list of character 
strings: 


Another example: 
DIM A(2,3) 


This statement creates a two-dimensional, 
numeric-variable array named A. Since the array does 
not include a type-declaration character, the array, by 
default, consists of single-precision values. 


Array A can be thought of as a table of rows and 
columns: 


The element in the second row, first column, is called 
A(1,0). 


Here is a sample program: 


10 DIM YEARS(3,4) 

20 YEARS(2,3)=84 

38 FOR ROW=@ TO 3 

40 FOR COLUMN=@ TO 4 

50 PRINT YEARS(ROW,COLUMN) ; 
68 NEXT COLUMN 

7@ PRINT 

80 NEXT ROW 


Results: 


QQOQ@Q 
QQQQ 
QQ QQ 


In this program, line 10 dimensions an array with 20 
elements (4 rows and 5 columns). Line 20 assigns the 
array element at position 2,3 the value of 84. The 
nested loops in lines 30—80 print the array asa 4 x 5 
matrix. 


Note: A scalar variable can have the same name as 
an array variable because A$ is different from any 
element in array A$ (n,...). 


Static and Dynamic Arrays 


Any array can be declared either static or dynamic. A 
dynamic array has its element space allocated during 
program execution. A static array has its element space 


Y allocated at compiletime. 


Because the memory addresses of static arrays are 
easier to calculate, programs that contain static arrays 
run faster. Also, static arrays generate less code than 
dynamic arrays. Dynamic arrays are more flexible. 
Once an array is allocated as static, for example, it 
cannot be redimensioned. Therefore, you must ensure 
that all static arrays are sufficiently dimensioned the 
first time. On the other hand, dynamic arrays can be 
redimensioned at any point in the program. 
Consequently, you can allocate a smaller amount of 
space initially, knowing that more space can always be 
allocated later. 


Note: Dynamic arrays must be redimensioned in 


the same number of dimensions, otherwise a 
Y compiletime error occurs. 
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The first reference or dimensioning of an array 
determines whether the array is statically or 
dynamically allocated. Once the allocation method is 
defined, it cannot be changed later in the program. 


Normally, any array that is declared using integer 

constants for the subscript upper bounds in a DIM 

statement is considered static. An array that is declared > 
using a variable or expression as a subscript upper 

bound is considered dynamic. 


If the first reference to an array is in an expression or 
assignment statement, the array is statically allocated 
with a default dimension of 10 in each subscript. This 
array cannot be deallocated by a dynamic ERASE, nor 
can it be redimensioned. 


To support dynamic arrays, several new language 
features have been added to the compiler. These 


include: 

2 REDIM Statement 

° ERASE Statement 

« $DYNAMIC Metacommand a 
« $STATIC Metacommand. 


Refer to these statements and metacommands in 
BASIC Compiler 2.00 Language Reference. 
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Chapter 8. Numeric and String 
Expressions 
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Introduction 


This section discusses numeric and string expressions 

and the operators available in BASIC. Examples are 

given to show how the operators work and how they 
& can be combined to perform useful functions. 


Numeric Expressions and Operators 


A numeric expression can be simply a numeric constant 
or variable. It can also be an operator, combining 
constants and variables to produce one numeric value. 


Numeric operators perform mathematical or logical 
operations, most often on numeric values, but 
sometimes on string values. They are called numeric 
operators because they produce a value that is a 
number. The compiler numeric operators can be 
divided into the following categories: 


Arithmetic 
Relational 

Logical 

Numeric Functions. 
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Arithmetic Operators 


Arithmetic operators perform the usual arithmetic 

operations in the standard mathematical order of 

preference; that is, when an expression contains more 
than one operation, they are carried out in the following 


order: ‘ea. 


Operator Operation Sample Expression 
A Exponentiation a AE 
_ Negation —X 
wf Multiplication, p Teaee § 
Floating-Point x/Y 
Division 
\ Integer Division X\Y 


MOD Modulo Arithmetic X MOD Y 


+,— Addition, X+ Y 


Subtraction X-Y ~ 


Although most of these operations probably look 
familiar to you, two of them— integer division and 
modulo arithmetic—need some explanation. 


Integer Division 


Integer division is denoted by a backslash (\). The 
operands are rounded to integers (in the range —32768 
through 32767) before the division is performed; the 
quotient is truncated to an integer. 


8-4 


Example: 


10 A = 10\4 
20 B = 25.68\6.99 
30 PRINT A;B 


Results: 


Ww 2: 


Modulo Arithmetic 


Modulo arithmetic is denoted by the operator MOD. It 
gives the integer value that is the remainder of an 
integer division. 


Example: 


19 A = 7 MOD 4 
20 PRINT A 


Result: 


3 


This result occurs because 7/4 is 1, with remainder 3. 
For example: 


PRINT 25.68 MOD 6.99 
Result: 
5 
The result is 5 because 26/7 is 3, with the remainder 5. 


(Remember, the compiler rounds when converting to 
integers. ) 
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Relational Operators 


Relational operators compare two values. Both of these 

values can be either numeric or string. The result of the 
comparison is either “‘true’”’ (—1) or “‘false’’ (0). This 

result is usually used to make a decision regarding 

program flow. See “IF Statement” in BASIC Compiler ‘o 
2.00 Language Reference. 


Operator Relation Tested Sample Expression 
= Equality X=Y 
<> or >< —=Inequality » sie ae 
pa kf 
< Less than » ant 
> Greater than Ay 
<=or=e=< Less than or X<=Y 
equal to be ip 
>=or=> #£Greater than X >= Y ~ 
or equal to > Sap f 


The equal sign is also used to assign a value to a 
variable. See ““LET Statement” in BASIC Compiler 
2.00 Language Reference. 


Numeric Comparisons 


When arithmetic and relational operators are combined 
in One expression, the arithmetic is always performed 
first. For example, the expression: 


X#¥ < (T-1)/Z 


is true (—1) if the value of X plus Y is less than the “» 
value of T—1 divided by Z. 
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String Comparisons 


String comparisons can be thought of as “‘alphabetic.”’ 
That is, a string is “less than’”’ another if the first letter 
of it comes before the other one alphabetically. 
Lowercase letters are “greater than’”’ their uppercase 
counterparts. Numbers are “‘less than”’ letters. 


Two strings are compared by taking one character at a 
time from each string and comparing the ASCII codes. 
See ‘““ASCII Character Codes,” in BASIC Compiler 
2.00 Language Reference. If all the ASCII codes are 
the same, the strings are equal. Otherwise, as soon as 
the ASCII codes differ, the string with the lower code 
number is less than the string with the higher code 
number. If, during string comparison, the end of one 
string is reached, the shorter string is said to be smaller. 
Leading and trailing blanks are significant. For 
example, all the following relational expressions are 
true (that is, the result of the relational operation is 
—1): 


elt hy < be 4 ihe 

"FILENAME" = "FILENAME" 
ya > gh © 

uh 0 be > hea” 

Tea” < af ef oy 


BS.< 71S (where B$ = "12543") 


All string constants used in comparison expressions 
must be enclosed in quotation marks. 


Logical Operators 


Logical operators perform logical, or boolean, 
Operations on numeric values. Just as the relational 
operators are usually used to make decisions regarding 
program flow, logical operators are usually used to 
connect two or more relations and return a true or false 
value to be used in a decision. See “‘IF Statement”’ in 
BASIC Compiler 2.00 Language Reference. 


8-7 


A logical operator takes a combination of true-false 
values and returns a true or false result. An operand of 
a logical operator is considered to be true if it is not 
equal to zero (like the —1 returned by a relational 
operator), or false if it is equal to zero. The number is 
calculated by performing the operation bit by bit. 


The logical operators are: NOT (logical complement), ‘% 
AND (conjunction), OR (disjunction), XOR (exclusive 

or), EQV (equivalence), and IMP (implication). Each 

operator returns results as indicated in the following 

table. (T indicates a true, or nonzero value. F indicates 

a false, or zero value.) The operators are listed in order 

of precedence. 


S 
> 


AND 


OR 


EF FY LL, 


X OR Y 


Pw Ex fy ee LL 


Pe i 


XOR 


Fy EX Ee LL, 


X XOR Y 


Pw Fx fy EY f, 


Pe YL 
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~ = 
= a 
Qe & me SRR 
<a = 
= ™ 
De by FH Ey Fe 
ME i pg eet et a 
> a 
8 
3 = 


Some examples of ways to use logical operators in 
decisions are: 


IF HE>6@ AND SHE<2@ THEN 1000 


Here, the result is true if the value of the variable HE is 
more than 6@ and the value of SHE is less than 20. 


50 IF NOT (P=-1) THEN 100 


Here, the program branches to line 100 if P is not equal 
to —1. Note that NOT (P=—1) does not produce the 
same result as NOT P. See the next section, ““How 
Logical Operators Work,” for an explanation. 


100 FLAG% = NOT FLAG% 


This example switches a value back and forth from true 
to false. 


How Logical Operators Work 


Operands are converted to integers in the range —32768 
to 32767. (If the operands are not in this range, an 
Overflow error results.) If the operand is negative, the 
twos complement form is used. This turns each 
operand into a sequence of 16 bits. The operation is 
performed on these sequences. That is, each bit of the 
result is determined by the corresponding bits in the 
two operands, according to the tables for the operator 
listed previously. A 1! bit is considered “‘true,”’ and a 0 
bit is ‘‘false.”’ 


Thus, you can use logical operators to test for a 
particular bit pattern. For instance, the AND operator 
may be used to “‘mask’”’ all but one of the bits of a 
status byte at a machine I/O port. 


The following examples show how the logical operators 
work. 


A = 63 AND 16 


Here, A is set to 16. Since 63 is binary 111111 and 16 
is binary 10000, 63 AND 16 equals 010000 in binary, 
which is equal to 16. 


Bea el ARDS 


B is set to 8. Since —1 is binary 11111111 11111111 
and 8 is binary 1000, —1 AND 8 equals binary 
QO000000000001000, or 8. 


C = 4 OR 2 


Here, C equals 6. Since 4 is binary 100 and 2 is binary 
010, 4 OR 2 is binary 110, which is equal to 6. 


K=2 
TWOSCOMP = (NOT X) + 1 


This example shows how to form the twos complement 
of anumber. X is 2, which is 10 binary. NOT X is 
then binary 11111111 11111101, which is —3 in 
decimal; —3 plus 1 is —2, the complement of 2. That is, 
the twos complement of any integer is the bit 
complement plus one. 


Note that if both operands are equal to either 0 or —1,a 
logical operator returns either O or —1. 


Numeric Functions 


A function is used like a variable in an expression to 
call a predetermined operation that is to be performed 
on one or more operands. BASIC has some built-in 
numeric functions that reside in the system, such as 
SOR (square root) and SIN (sine). 


You can also define your own numeric functions using 
the DEF FN statement. See ““DEF FN Statement” in 
BASIC Compiler 2.00 Language Reference. 


Order of Execution 


In the previous sections, the categories of numeric 
operations have been discussed in their order of 
precedence, and the precedence of each operation 
within a category has been indicated in the discussion 
of the category. In summary: 


1. Function calls are evaluated first. 


2. Arithmetic operations are performed next, in this 


order: 

« A 

. unary — 
w * 9 
NX 

° MOD 

* +a - 


3. Relational operations are performed next. 


4. Logical operations are performed last, in this 


order: 

« NOT 
e« AND 
e OR 

e - KOR 
« EQV 
e IMP. 


Because this is an optimizing compiler, the order in 
which operations are performed is determined by the 
compiler. The compiler performs the operations in the 
order that produces the most efficient code. To insure 
that operations are performed in the order that you 
intend, use parentheses. Operations within parentheses 
are performed first. 


Here are some sample algebraic expressions and their 
BASIC counterparts: 


Algebraic Expression BASIC Expression 
X+Y X+Y 

oe X- Y/Z 
a 
XY ** 

5 X*Y/Z 
ae (X+Y)/Z 
ar (XA2)AY 

Z 
x Y XA(Y*Z) 
X(-Y) X*(-Y) 


Note: Two consecutive operators must be 


separated by parentheses, as shown in the X*(—Y) 
example. 
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String Expressions and Operators 


A string expression can be simply a string constant or 
variable, or it can combine constants and variables by 
using operators to produce one string value. 


String operators are used to arrange character strings in 
different ways. The two categories of string operators 
are: 


* Concatenation 
e String Functions. 


Note that although you can use the relational operators 
=, <>, <,; >, <=, and >= to compare fwo strings, 
these are not considered to be “‘string operators”’ 
because they produce a numeric result, not a string 
result. Read through ‘Relational Operators”’ earlier in 
this chapter for an explanation of how you can compare 
strings using relational operators. 


Concatenation 
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Joining two strings together is called concatenation. 
Strings are concatenated using the plus symbol (+). 
For example: 


10 COMPANY$ = "IBM" 
20 TYPE$ = " Personal’ 


30 FULLNAME$ = TYPE$ + " Computer” 
40 PRINT COMPANY $+FULLNAME $ 


Result: 


IBM Personal Computer 


String Functions 


A string function is like a numeric function except that 
it returns a string result. A string function can be used 
in an expression to call a predetermined operation that 
is to be performed on one or more operands. BASIC 
has built-in string functions that reside in the system, 

YY such as MID$, which returns a string from the middle 
of another string, and CHR$, which returns the 
character with the specified ASCII code. 


You can also define your own string functions using the 
DEF FN statement. See ‘““DEF FN Statement” in 
BASIC Compiler 2.00 Language Reference. 
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Appendix A. Memory Information 


© This appendix contains information relating to the 

BASIC compiler’s memory, including a memory map 
and details on the storage of variables, the keyboard 
buffer, and the search order for adapters. 


Refer to the IBM Personal Computer Technical 
Reference manual for technical information that is not 
in this manual or in BASIC Compiler 2.00 Language 
Reference. 


Memory Map 
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This section contains illustrations of runtime memory 
maps for programs linked to the two runtime libraries: 
BASRUN20.LIB and BASCOM20.LIB. 


space for .EXE loader 


BASRUN20.EXE 


LNA Heap 


String space 


BC__DS 
BC__CN 
BC__FT 


BC__DATA 
(user variables) 


DATA 
CONST 


COMMON (BLANK) 


DSEG 


(DATASG) 


<modname>__CODE 
(compiled program) 


DOS area 


Interrupt vectors 


Top of memory 


Top of user space: 
Communications buffers, 
Large Numeric Array Heap. 
Paragraph - aligned 


Top of string space (dynamic 
boundary, can not exceed 
64K from DS:) 


Bottom of string space 
(dynamic boundary) 


Top of user stack 
(default — 768 bytes) 


Bottom of user stack 
Data statements 
Numeric and string constants 
Floating-point temporaries 


BASIC program variables 


Optional data area for 
other-language subprograms 


COMMON area (varies with program) 


Runtime module data and constants 
(fixed size — approx. 6K) 


DS,ES,SS:0000 
Other-language subprograms 


Separately compiled BASIC 
subprograms (no size restriction) 
Bottom of user area 


0000:0000 


Memory Map continued... 


space for .EXE loader 


LNA Heap 


String space 


uid: | IIR 


BC__DS 
BC__CN 
BC__FT 


BC__DATA 
(user variables) 


DATA 
CONST 


COMMON (BLANK) 


a 
DSEG eee 
(DATASG) 

oe 


<modname>__CODE eed 
(compiled program) 


DOS area 


Interrupt vectors 


Top of memory 


Top of user space: 
Communications buffers, 
Large Numeric Array Heap. 
Paragraph - aligned 


Top of string space (dynamic 
boundary, can not exceed 
64K from DS:) 


Bottom of string space 
(dynamic boundary) 


Top of user stack 
(default — 768 bytes) 


Bottom of user stack 
Data statements 
Numeric and string constants 
Floating-point temporaries 


BASIC program variables 


Optional data area for 
other-language subprograms 


COMMON area (varies with program) 


.EXE file loader data (64 bytes) 


Runtime module data and constants 
(fixed size — approx. 6K) 


DS,ES,SS:0000 
Other-language subprograms 


Separately compiled BASIC 
subprograms (no size restriction) 
Bottom of user area 


0000:0000 
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PCr 


Note 2: 
For PCjr <128K Pood See Note 2 


screen buffer. 
space for .EXE loader 


DS:0000 
String space 


dynamic array heap 
ee EXE file loader data 
(64 bytes) 


Top of memory 


BC__DS Data statements 
BC__CN Numeric and string constants 
BC__FT Floating point temporaries 
BC__DATA oe 
(user variables) Basic program variables 


Optional data area 
CONST for assembly language 


(assembly Language) subprograms 


COMMON area 
(size varies) 


Runtime module data 
i. and constants 
(fixed size—approx. 3K) 


DS, ES, $S:0000 


DATA 
CONST 
(runtime _ RT__ DATA) 


Free memory ——+— (if available) 


So Botton of user area 
BC_ CODE complied BASIC code 
(compiled program) (64K maximum) 
Note 1: 
For PCjr >128K se See Note | 


screen buffer 
if device driver 
is installed. DOS area 


Interrupt vectors 


0000:0000 
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How Variables Are Stored 


Scalar variables are stored in BASIC’s data area as 


follows: 
a Byte 0 1 2 3 4 4+/ength 
& data 
2, 3, 4, or 8 bytes 
type identifies the type of variable: 
Z integer 
3 string 
4 single-precision 
8 double-precision 


name is the name of the variable. The first two 
characters of the name are stored in bytes 1 
and 2. Byte 3 tells how many more 
characters are in the variable name. These 
additional characters are stored starting at 
byte 4. 


Note that this means any variable name takes 
up at least 3 bytes. A 1-character or 
2-character name occupies exactly 3 bytes; 
an x character name occupies x+1 bytes. 


data follows the name of the variable, and can be 
2, 3, 4, or 8 bytes long (as described by type). 
The value returned by the VARPTR function 
points to this data. 
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For string variables, data is the string descriptor: 


¢ String descriptors occupy 2 words (4 bytes). 


¢ The first word of the string descriptor contains the 
length of the string (0 to 32767). 


e The second word of the string descriptor contains “y 
the offset of the string relative to the BASIC 
Compiler’s data segment. 


For numeric variables, data contains the actual value 
of the variable: 


e Integer values are stored in 2 bytes, with the low 
byte first and the high byte second. 


e Single-precision values are stored in 4 bytes in 
BASIC’s internal floating-point binary format. 


e Double-precision values are stored in 8 bytes in 
BASIC’s internal floating-point binary format. 
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Dynamic Array Descriptors 


When a base of a dynamic array is used as an argument 

in a CALL statement, the offset of the descriptor is 

given in relation to the BASCOM data segment. 

Subprograms that want to access the dynamic array 

must use this descriptor to determine the appropriate 
& address. The descriptor format is as follows: 


O 2 3 4 8 
b Number length of | length of length of 
eh type | of dimension | dimension dimension 
meenion dim. N N-1 1 


base address Offset 0 —2 bytes 


This word value determines the start of 
the dynamic array. For numeric arrays, 
the starting address is xxxx:0000 where 
xxxx is the base value. Note that 
numeric arrays always start on a 
paragraph boundary. For string 
dynamic arrays, the starting address is 
BASCOM _DS:xxxx as strings and 
their descriptors are still within the 
BASCOM data segment. 


type Offset 2 — 1 byte 


This byte value determines the type of 
element defined in the array (and its 
length). The possible values of this byte 
are: 


1 — Integer, each element is 2 
bytes. 

2 — Single-precision real, each 
element is 4 bytes. 
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dimensions 


total size 


dimension size 


3 — Double-precision real, each 
element is 8 bytes. 

4 — String, each element is a 
4-byte string descriptor. 


Offset 3 — 1 byte 
The value of this byte determines the 


actual length of the dynamic array 
descriptor since each extra dimension 


increases the descriptor size by 2 bytes. 


Offset 4 — 4 bytes 


These 2 words (low-order word 
first/high-order word second) are the 
total array size in bytes. This value is 
computed by multiplying the size of 
each dimension together with the 
element size. 


Offset 8 — length of dimension N — 2 
bytes 

Offset 10 — length of dimension N-1 
— 2 bytes 


Offset 8 + ((N-1)*2) — length of 
dimension 1 — 2 bytes 


Example: 


For the dynamic array defined by the statement: 
REDIM (3,6,9,12) 


with a descriptor at DS:0BAO, the descriptor would 


&Y have the following contents: 
DS:O0BAO 25 7C BASE ADDRESS 7C€25:0000 
OBA2 02 SINGLE-PRECISION (ELEMENT SIZE OF 4 BYTES) 
OBA3 O04 FOUR DIMENSIONS DEFINED 


OBA4 EO 38 00 O00 SIZE OF ARRAY 000038E0(HEX)=14560 
DIMENSION 1 SIZE 4 
DIMENSION 2 SIZE = 7 


DIMENSION 3 SIZE 10 
DIMENSION 4 SIZE = 13 
ELEMENT SIZE i 
TOTAL SIZE = 4*7#*10*13*4 14560 
OBA8 OD 00 DIMENSION 4 SIZE 13 
OBAA OA 00 DIMENSION 3 SIZE = 10 
OBAC 07 00 DIMENSION 2 SIZE 7 
OBAE 04 00 DIMENSION 1 SIZE = 4 


Keyboard Buffer 


& Characters typed on the keyboard are saved in the 

keyboard buffer until they are processed. Up to 15 
characters can be held in the buffer; if you try to type 
more than 15 characters, the computer beeps. 


INKEY$ reads only one character from the keyboard 
buffer even if there are several characters pending 
there. INPUT$ can be used to read multiple 
characters; however, if the requested number of 
characters is not already present in the buffer, BASIC 
waits until enough characters are typed. 


The system keyboard buffer can be cleared by the 
following lines of code: 


WHILE INKEY$ <> "":WEND 
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Search Order for Adapters 
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The printers associated with LPT1, LPT2, and LPT3 
are assigned when you switch your computer on. The 
system looks for printer adapters in a particular 
sequence; the first printer adapter found becomes 
LPT1; the second adapter (if one exists) becomes 
LPT2; and the the third (if it exists) becomes LPT3. 
The search order is as follows: 


1. AnIBM Monochrome Display and Printer Adapter 

2. A Printer Adapter 

3. A Printer Adapter that has been modified to 
change its base address. 


If a printer was rerouted using the MODE command 
from DOS, the change is effective in BASIC as well. 


The communication devices COM1: and COM2: are 
assigned in a manner similar to printers. Their search 
order is: 


1. A primary Asynchronous Communications 
Adapter 

2. An alternate Asynchronous Communications 
Adapter. 


Appendix B. Communications 


This appendix describes the BASIC statements required 
&Y to support RS-232 asynchronous communication with 
other computers and peripherals. 


Opening a Communications File 


OPEN ‘“‘COM... allocates a buffer for input and output 
in the same fashion as OPEN for disk files. See 
““OPEN “COM.... Statement” in the BASIC Compiler 
2.00 Language Reference. 


Communication I/O 


Since each communications adapter is opened as a file, 
all input/output statements that are valid for disk files 
Y are also valid for communications. 


Communications sequential input statements are the 
same as those for disk files. They are: 


INPUT # 
LINE INPUT # 
INPUTS. 


Communications sequential output statements are also 
the same as those for disk files, and are: 


PRINT # 
PRINT # USING 
WRITE #. 


See “INPUT” and “PRINT” in BASIC Compiler 2.00 
Language Reference for details of coding syntax and 
usage. 
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GET and PUT for Communications Files 


GET and PUT are only slightly different for 
communications files than for disk files. They are used 
for fixed length I/O from or to the communications 
file. Instead of specifying the record number to be read 
or written, you specify the number of bytes to be 
transferred into or out of the file buffer. This number 
cannot exceed the value set by the LEN option on the 
OPEN ‘‘COM... statement. See ““GET” and “PUT” in 
BASIC Compiler 2.00 Language Reference. 


I/O Functions 


The most difficult aspect of asynchronous 
communication is processing characters as fast as they 
are received. At rates of 1200 bps or higher, it may be 
necessary to suspend character transmission from the 
other computer long enough to “‘catch up.’’ This can be 
done by sending XOFF (CHR$(19)) and XON 
(CHR$(17)) to the other computer. XOFF tells the 
other computer to stop sending, and XON tells it to 
Start sending again. 


Note: This is a commonly used convention, but it 
is not universal. Whether it is valid depends on the 
protocol implemented between you and the other 
computer or peripheral. 


BASIC Compiler 2.00 provides three functions that 
help determine when an “overrun” condition is likely to 
occur. These are: 


LOC (f) 
LOF(f) 
EOF(f). 


Note: A Communication buffer overflow can occur 
if a read is attempted after the input buffer is full 
(that is, when LOF(f) returns O). 


INPUTS Function 


The INPUT$ function is preferred over the INPUT # 
and LINE INPUT # statements when reading 
communications files, since all ASCII characters may 
be significant in communications. INPUT # is the least 
desirable because input stops when a comma or carriage 
return is seen. LINE INPUT # stops when a carriage 
return is seen. 


INPUTS$ allows all characters read to be assigned to a 
string. INPUT$(n,f ) returns n characters from the #f 
file. The following statements are efficient for reading 
a communications file: 


1@ WHILE NOT EOF(1) 
20 A$=INPUT$(LOC(1) ,#1) 


(process data returned in A$) 


100 WEND 


When there are characters in the buffer, line 20 assigns 
them to A$, and they are processed. If there are more 
than 255 characters in the buffer, only 255 are returned 
at a time to prevent a String overflow error. Since 
EOF(1) is false, input continues until the input buffer is 
empty. This procedure is simple, concise, and fast. 


To process characters quickly, avoid examining every 
character as you receive it. If you are looking for 
special characters (such as control characters), you can 
use the INSTR function to find them in the input string. 


A Sample Program 
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The following program allows the IBM Personal 
Computer to be used as a conventional ““dumb”’ 
terminal in a full duplex mode. This program assumes a 
300 bps line and an input buffer of 256 bytes. 


16 REM dumb terminal example 

26 ‘set screen to monochrome text mode 

cy Beg and set width to 46 

46 SCREEN 6,6: WIDTH 46 

5@ ‘turn off key display; clear screen 

66 ' make sure all files are closed 

76 KEY OFF: CLS: CLOSE 

86 ‘define numeric variables as integer 

96 DEFINT A-Z 

166 'define true and false 

116 FALSE=8: TRUE=NOT FALSE 

126 ‘define the XON, XOFF characters 

136 XOFF$=CHR$(19): XON$=CHR$(17) 

148 ‘open communications to file number 1, 
156 ' 366 bps, EVEN parity, 7 data bits 
166 OPEN "COM1:366,E,7" AS #1 

176 'use screen as a file, just for fun 
186 OPEN "SCRN:" FOR OUTPUT AS #2 

198 ‘turn cursor on 

266 LOCATE ,,1 

466 PAUSE=FALSE: ON ERROR GOTO 9666 

496 ' | 
566 ‘send keyboard input to com line | 
516 B$=INKEY$: IF B$<>"" THEN PRINT #1,B$; 

526 ‘if com buffer is empty, check key in 

536 IF EOF(1) THEN 518 

546 ‘if buffer more than 1/2 full, then 

558 ‘set PAUSE flag to say input suspended, 

566 'send XOFF to host to stop transmission 

576 IF LOC(1)>128 THEN PAUSE=TRUE 

575 PRINT #1,XOFF$ 

588 ‘read contents of com buffer | 
596 A$=INPUT$(LOC(1),#1) 

666 ‘remove linefeeds to avoid double spaces 


616 ‘when input displayed on screen 

626 LFP=6 

625 ‘look for linefeed 

636 LFP=INSTR(LFP+1,A$,CHR$( 16) ) 

646 IF LFP>S THEN MID$(A$,LFP,1)=" " 

645 GOTO 636 

658 ‘display com input, and check for more 
666 PRINT #2,A$;: IF LOC(1)>6 THEN 576 

676 ‘if transmission suspended by XOFF, 
686 'resume by sending XON 

696 IF PAUSE THEN PAUSE=FALSE 

695 PRINT #1,XON$; 

766 ‘check for keyboard input again 

716 GOTO 516 

8999 'if error, print its number and retry 
9666 PRINT "ERROR NO.";ERR: RESUME 


Notes on the Program 


e Asynchronous communication implies character 
I/O as opposed to line or block I/O. Therefore, 
all PRINTs (either to communications file or to 
yy screen) are ended with a semicolon. This stops the 
carriage return normally issued at the end of the 
list of values to be printed. 


° Line 90, where all numeric variables are defined as 
integers, is coded because any program looking for 
speed optimization should use integer counters in 
loops where possible. 


¢ Note in line 510 that INKEY$ returns a null string 
if no character is pending. 


Operation of Control Signals 


\& The output from the Asynchronous Communications 
Adapter conforms to the Electronic Industries 

Association (EIA) RS-232-C standard for interface 
between Data Terminal Equipment (DTE) and Data 
Communications Equipment (DCE). This standard 
defines several control signals that are transmitted or 
received by your IBM Personal Computer to control the 
interchange of data with another computer or 
peripheral. These signals are DC voltages that are 
either ON (greater than +3 volts) or OFF (less than —3 
volts). See the IBM Personal Computer Technical 
Reference for details. 


Control of Output Signals with OPEN 


When you start BASIC on your IBM Personal 
Computer, the RTS (Request To Send) and DTR (Data 
Terminal Ready) lines are held off. When an OPEN 
‘“COM... statement is performed, both of these lines are 
normally turned on. However, you can specify the RS 
option in the OPEN “COM... statement to suppress the 
RTS signal. The lines remain on until the 
communications file is closed (by CLOSE, END, NEW, 
RESET, SYSTEM, or RUN without the R option). 
Even if the OPEN “COM... statement fails with an 
error (as described below), the DTR line (and RTS line, 
if applicable) is turned on and stays on. This allows 
you to retry the OPEN without having to execute a 
CLOSE. 


Use of Input Control Signals 


Normally, if either the CTS (Clear To Send) or DSR 
(Data Set Ready) lines are off, an OPEN “‘COM... 
statement does not execute. After one second, BASIC 
returns a Device timeout error (error code 24). The 
Carrier Detect (sometimes called Receive Line Signal 
Detect) can be either on or off; it has no effect on the 
operation of the program. 


You can specify how you want these lines tested with 
the RS, CS, DS, and CD options on the OPEN 
‘““COM... statement. See “OPEN“COM... Statement” 
in BASIC Compiler 2.00 Language Reference. 


If any of the signals being tested are turned off while 
the program is executing, I/O statements associated 
with the communications file do not work. For 
example, when you execute a PRINT # statement after 
the CTS or DSR line is turned off, a Device fault (code 
25) or Device timeout (code 24) error occurs. The RTS 
and DTR remain on even if such an error occurs. 


You can test for a line disconnect by using the INP 
function to read the bits in the MODEM Status 
Register on the Asynchronous Communications 
Adapter. See the following section, “‘Testing for 
Modem Control Signals,”’ for details. 


& Testing for Modem Control Signals 


Four input control signals are picked up by the 
Asynchronous Communications Adapter. These signals 
are CTS and DSR (described previously), Carrier 
Detect (sometimes called Received Line Signal Detect) 
(pin 8), and Ring Indicator (pin 22). You can specify 
how you want to test the CTS, DSR, and CD lines with 
the OPEN “‘COM... statement. Ring Indicator is not 
used at all by the communications function in the 
compiler. 


If you need to test for any of these signals in a program, 
you can check the bits corresponding to these signals in 
the MODEM Status Register on the Asynchronous 
Communications Adapter. To read the 8 bits in this 
register, use the INP function—INP(&H3FE) to read 
the register on a primary communications adapter and 
INP(&H2FE) to read it on an alternate communications 
adapter. See the ““Asynchronous Communications 
Adapter”’ section of the IBM Personal Computer 
Technical Reference manual for a description of which 
bits in the Status Register correspond to which control 
signals. You can also use the Delta bits in this register 
to determine if transient signals have appeared on any 
of the control lines. Note that for a control signal to 
have meaning, the pin corresponding to that signal must 
be connected in the cable to your modem or to the 
other computer. 


You can also test for bits in the Line Status Register on 
the Asynchronous Communications Adapter. Use 
INP(&H3FD) to access this register on a primary 
communications adapter, and INP(&H2FD) to access it 
on an alternate communications adapter. 


Again, the bits are described in the IBM Personal 
Computer Technical Reference. These bits can be used 
to determine what types of errors have occurred on 
receipt of characters from the communications line or 
whether a break signal has been detected. 


Direct Control of Output Control Signals 


You can control the RTS or DTR control signals 
directly from a BASIC program with an OUT 
statement. The on/off states of these signals are 
controlled by bits in the MODEM Control Register on 
the Asynchronous Communications Adapter. The 
address of this register is €H3FC on a primary 
communications adapter and &H2FC on an alternate 
communications adapter. The IBM Personal Computer 
Technical Reference describes which of these bits 
correspond to which signals. 


You can also change bits in the Line Control Register 
on the Asynchronous Communications Adapter. Be 
careful in modifying these bits because most of them 
have been set by the compiler when an OPEN 
statement is executed and changing a bit can cause 
communications failure. The Line Control Register is 
at address &H3FB on a primary communications 
adapter and at address &H2FB on an alternate 
communications adapter. 


When changing bits in either the MODEM Control 
Register or the Line Control Register, first read the 
register (with an INP function) then rewrite the register 
with only the pertinent bit or bits changed. 


A bit you may wish to control in the Line Control 
Register is bit 6, the Set Break bit. This bit permits you 
to produce a Break signal on the communications send 
line. 


A Break is often used to signal a remote computer to 
stop transmission. Typically a Break lasts for 1/2 
second. To produce such a signal, you must turn on the 
Set Break, wait for the desired time of the Break signal, 
and then turn the bit off. The following BASIC 
statements produce a Break signal of about 1/2 second 
duration on a primary communications adapter. 


IC%Z=INP( &H3FB) 

‘get contents of modem register 

IZ%=1C% OR &H4@ 

‘turn ON the Set Break bit 

OUT &H3FB,1Z% 

‘transmit to modem control register 

FOR I=1 TO 5@0@@: NEXT I 

‘short delay 

OUT &H3FB,IC% ‘turn Set Break bit OFF in register 


Note: The delay in line 70 varies depending on 
the particular IBM computer you are using. 


Communication Errors 


Errors occur on communication files in the following 
order: 


1. When opening the file: 


a. Device timeout if one of the signals to be 
tested (CTS, DSR, or CD) is missing. 


2. When reading data: 
a. Com buffer overflow if overrun occurs. 


b. Device I/O error for overrun, break, parity, or 
framing errors. 


c. Device fault if you lose DSR or CD. 


3. When writing data: 


a. 


Device fault if you lose CTS, DSR, or CD ona 
Modem Status Interrupt while BASIC was 
doing something else. 


Device timeout if you lose CTS, DSR, or CD 
while waiting to put data in the output buffer. 


Appendix C. Modular Programming 


This appendix is comprised of two sections that contain 

& important information about the concepts and details of 
modular programming. The first section addresses the 
specific rules, conventions, and advantages of calling 
BASIC Compiler 2.00 subprograms. The second 
section details the necessary guidelines for calling IBM 
Macro Assembler subprograms. 


Building Programs with Separate 
Compilations 


BASIC Compiler 2.00 enables you to develop 
applications that consist of separately compiled source 
files. In the IBM BASIC Compiler Version 1.00, 

& programs consisted of only one source file, which we 
call a module. A module is an individually compiled 
body of code. For many programming needs, a 
one-module program is adequate. Large applications, 
however, are often more efficiently developed as a 
system of modules. If an application is developed by a 
team of programmers, for example, it is expedient to 
divide the application into two or more modules that 
can logically be developed, tested and compiled 
independently from one another. Thus, one application 
program may draw on code located in two or more 
separate modules. Of course, a program with one main 
program and no subprograms is accepted by BASIC 
Compiler 2.00, but the ability to divide related 
subprograms into separate, reusable modules provides 
flexibility in developing and maintaining complex 

&Y applications. 


A multimodule application is comprised of one or more 
main modules and one or more external modules. 


Program execution begins within the main module in a 
code section called the main program. The main 
module may also contain one or more subprograms. 
External modules contain one or more subprograms and 
(optionally) a main program. 


Defining Subprograms a) 


BASIC subprograms are executable sections of code 
that are declared and delimited by the SUB and END 
SUB statements. Subprograms are usually designed to 
perform a specific process or procedure. As such, 
BASIC subprograms are similar to multiline functions. 
Two key differences between a BASIC Compiler 2.00 
subprogram and a function are: 


e A function must return a value that is equated to 
the function name. A subprogram does not return 
a value associated with its name; therefore, a 
subprogram cannot appear as part of an 
expression. 


* A function must be defined before it can be called; 
that is, a function call statement cannot 
sequentially precede a define-function statement 
within the source code body. This restriction does 
not apply to subprograms; hence, forward calls 
between modules are possible. 


IBM Macro Assembler subprograms can also be linked 
to modules produced by the BASIC Compiler 2.00. 
Assembler subprograms must have their entry points 
defined by the PUBLIC pseudo-op. See the following 
section ‘“‘Structuring Your Assembly Language 
Program ”’ for details. 


Calling Subprograms 


BASIC subprograms and assembler subprograms 
receive program control when a CALL statement is 
executed in either a main program or another 
subprogram. See the CALL statement in BASIC 
Compiler 2.00 Language Reference for details on 
vY syntax. Within a BASIC Compiler 2.00 source module, 
a CALL statement can be issued from the main 
program to an internal subprogram or from one internal 
subprogram to another internal subprogram. 
Intermodule calls (from one module to another) can 
also be performed by either a main program or a 
subprogram, however, the following restriction applies: 


The main program of an external module cannot be 
accessed by a call from another module. 
Transferring control from one main program to 
another requires the use of the CHAIN statement. 
See the CHAIN and COMMON statements in 
BASIC Compiler 2.00 Language Reference for 
details. 


& The following diagram illustrates the calling pattern in a 
three-module application. In this application, the main 

module issues calls to the subprograms in two external 
modules, A and B. Note that the main programs in 
external modules cannot be called from the main 
module. Note also that a subprogram in an external 
module can call a subprogram in another external 
module, as in the A2 to B1 call. 


Program Structure Using Separate 
Compilations 


Main Module 


Main Program 


Subprogram 
M1 


Subprogram 
M2 


Subprogram 
M3 


External Module A 


Main program | 
(optional) © : 


nes bprogram 


ay eee ‘ 


External Module B 


Main program 
(optional) 


Subprogram 
B1 


Passing Parameters With the CALL Statement 


In this section we refer to formal parameters and 
arguments. Formal parameters refer to the position of a 
value in the list of values being passed. Formal 
parameters are like place markers; they help you keep 
track of which argument you are using. The argument 
is the value itself. The term subprogram, when used by 
itself, is a reference to both BASIC and assembly 
language subprograms. 


A CALL statement passes values two ways: 


The memory location (variable) of the actual value 
(argument) is passed to the subprogram. Because 
the receiving subprogram is informed of the 
argument’s actual location, it can perform 
operations on the argument. This type of 
parameter passing is called passing by reference. 
Passing by reference, therefore, means that the 
receiving subprogram can change the value of the 
variable in the calling routine by assigning a new 
value to its corresponding formal parameter. Of 
course, an assignment statement or any other 
statement that assigns values (for example, READ, 
INPUT) would perform this task. From the 
perspective of the receiving subprogram, the 
formal parameter is an input variable and an 
output variable. That is, when a formal parameter 
is passed to a subprogram and operated on, the 
value that results from the operation is assigned 
(passed back) to the variable in the calling routine. 


A copy of the value (argument) is assigned to a 
temporary memory location (temporary variable). 
The location of the copy (not the original value) is 
then passed as a formal parameter to the 
subprogram. Consequently, when an operation is 
performed on the passed variable within the called 
subprogram, the passed value’s corresponding 
original value in the calling routine is not changed. 


Because the net result of this process is equivalent 
to passing by value, we call this process by that 
name. 


Note: Do not confuse passing by value (as 

defined above) with the conventional usage of 
passing by value. In conventional passing by 

value, the actual value of the argument is “o 
passed to the called subprogram. 


From the perspective of the receiving subprogram, 
a formal parameter that is passed by value is only 
an input variable. That is, the value that is input 
into the subprogram is not assigned to the same 
named variable in the calling routine once the 
calling routine regains execution control. 


In summary, passing by value ensures that the 
variable in the calling routine is not changed when 
that variable is operated on in the called 
subprogram. 


Passing By Reference “a 


Simple variables and array elements can be passed by 
reference to subprograms. The following example 
illustrates how to pass a simple variable argument by 
reference using a CALL statement. 


A=5 : B =@ 
CALL SQUARE(A,B) 
PRINT A,B 

END 


SUB SQUARE (X,Y) STATIC 
X 
END SUB 


This example prints the results 5 and 25. The 
subprogram SQUARE has substituted the computed “» 
value of the formal parameter Y for the argument of B. 


Note that the formal parameter symbols in the 
subprogram (X and Y) do not have to be the same as 
the symbols that are passed (A and B)—X points to the 
same memory location as the simple variable A. As 
place markers, however, X and Y do have to 
correspond to A and B, respectively, to yield 5 and 25, 
respectively. 


Array arguments can also be passed by reference to 
BASIC Compiler 2.00 subprograms by specifying the 
SHARED attribute in either the DIM, REDIM, or 
COMMON statement of the calling routine. See the 
DIM, REDIM, and COMMON statements in BASIC 
Compiler 2.00 Language Reference for details on 
syntax. 


Passing By Value 


If a simple variable or array element is enclosed in 
parentheses, it is passed by value. For example, if the 
CALL SQUARE statement in the above example were 
changed to: 


CALL SQUARE(A,(B)) 


the results printed would be 5 and O. In this case ‘‘(B)”’ 
is passed by value, therefore, the subprogram cannot 
change its value. 


Array arguments can also be passed by value to BASIC 
Compiler 2.00 subprograms. To specify an array 
argument, follow the array name with parentheses. For 
example: 


DIM ARRAY1(5,1@) ,ARRAY2(5,1@) ,TOTAL(5,1@) 


CALL MATADD2(5,1@,ARRAY1() ,ARRAY2(),TOTAL()) 


This routine passes both scalars and arrays; the arrays 
are indicated by the empty parentheses after the 
variable names. 


subprograms or assembly language subprograms. An 

argument expression can be any valid BASIC Compiler 

2.00 expression except simple variables and array “o 
elements. As such, an expression can be as simple as 

the integer “‘1’’ or a complex combination of operands 

and operators. The expression, “‘B + 5’’, for example, 

can be placed in an argument list as: 


Expressions can also be passed as arguments to BASIC 


CALL SUB3(A,B + 5) 


When an expression is passed as an argument in a 
CALL statement, it is assigned to a variable of the 
same type (just as simple variables and array elements 
are assigned). It is effectively passed by value, 
therefore, rather than by reference. 


Common Errors In Calling Subprograms 


Two types of errors commonly occur in calling 
subprograms. The most frequent type is mismatched 
argument and parameter lists where the order, type or 
number of arguments passed to a BASIC Compiler 2.00 
subprogram (or assembly language subprogram) do not 
match the corresponding formal parameters in the 
subprogram. A second, more subtle type of error 
occurs when variables are aliased. Aliasing occurs 
when an argument passed to a subprogram can be 
referenced in the subprogram in more than one way. 


The BASIC Compiler 2.00 does not check for 
mismatched argument and parameter lists. Error 
messages are not generated, but noticeable side effects 
can occur. Consider, for instance, what happens when 


type mismatches between integer and double-precision 
arguments occur. 


In this example, we call SQUARE, defined previously 
under ‘‘Passing By Reference,”’ with a floating-point 
constant as the first argument: 


CALL SQUARE(5,B) 
PRINT B 


& The expected result is 25. However, the subprogram 
SQUARE is expecting a double-precision argument, not 
an integer. Since the first argument passed was not 
double-precision, the printed result will probably not be 
25. SQUARE should be called with an argument of 5.0 
to insure that the desired result is produced. 


The BASIC Compiler 2.00 does not support or check 
for aliasing. Aliasing commonly occurs when the same 
nonexpression argument is passed more than once to a 
subprogram. Passing variables both in COMMON and 
as an argument, or passing both an array element and 
the array itself can also cause aliasing. 


In summary, you should exercise care when passing 

parameters to subprograms. See the following section 

‘Calling Assembly Language Subprograms”’ for details 
& on the rules of calling assembly language subprograms. 


Scope of Variables 


The scope of a variable is the portion of a program 
within which the definition of the variable remains 
unchanged. Within a module, variables and arrays that 
are referenced or declared in a subprogram are 
generally considered to be /ocal to the subprogram. 
That is, using the same-named variable or array within 
two separately defined subprograms—without 
specifically passing that variable as an argument—does 
not establish that the same memory location is being 
used to represent that variable. 
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The SHARED statement, STATIC statement, and 
SHARED attribute can be used to qualify the scope of 
a variable or an array. 


Note: Do not confuse the SHARED statement 
with the SHARED attribute. The differences are 
discussed below. 


Shared Variables 


By using either the SHARED statement in a 
subprogram or the SHARED attribute in COMMON, 
DIM, or REDIM statements at the main program level 
of the module, you can access variables and arrays 
without passing them to a subprogram as parameters. 
The SHARED attribute is used for sharing variables 
and arrays among all subprograms within one module. 
The SHARED statement is used within a specific 
subprogram to qualify variables and arrays within that 
subprogram only. 


To create a global variable (that is, a variable that can 
be accessed throughout a given module), place the 
SHARED attribute directly after the keyword in a 
COMMON, DIM or REDIM statement. For example: 


COMMON SHARED A,B,C 
DIM SHARED X,Y ,ARRAY(190,19) 
REDIM SHARED ZARRAY(N%) 


Note that the DIM statement can be used to identify 
attributes of scalar variables. 


Within a subprogram, main program level variables can 
be accessed by using the SHARED statement. Only 
the variables that are included in the SHARED 
statement and used in the main program are accessible 
to the subprogram. 


For example: 


DIM A,B,C,P(190) ,Q(100) 


SUB HNRY STATIC 
SHARED A,B,P(),Q() 


END SUB 


In this example, all main program variables and arrays 
except C are shared with the subprogram HNRY. 


Static Variables 


When declared, initial values of zero and null, 
respectively, are assumed for numeric and string 
variables. If the subprogram is exited and then 
reentered, however, the values retained for the 
variables are affected by how the individual program is 
implemented. Declaring the variables in a STATIC 
statement guarantees that the previous values are 
retained. 


Values of arrays can also be guaranteed by declaring 
the array ina STATIC statement. Any arrays declared 
with the STATIC statement are automatically allocated 
dynamically. Such arrays are not allocated, however, 
until they are dimensioned (with a DIM statement) or 
redimensioned (with a REDIM statement). 


Note: Do not confuse the STATIC statement with 
the $STATIC metacommand. The $STATIC 
metacommand affects the way space is allocated 
for arrays. The STATIC statement designates 
variables or arrays as local to a subprogram and 
preserves their values when the subprogram is 
exited and reentered. 
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STATIC variables or arrays override any shared 
variables or arrays with the same name. 


The STATIC statement can also be used inside 
multiline function definitions to declare a variable as 
local to that function only. 


Here are two examples: “o 
STATIC 1%,J0% 


STATIC A,B,C 402), %(2) ,Z(1) 
REDIM X(1%,J%) ,¥(18,20) ,Z(3) 


The first STATIC statement declares the integer 
variables 1% and J% as local. The second STATIC 
statement declares variables A, B, C and arrays X, Y 
and Z as local. Note that the number in the array 
parentheses is the number of dimensions in the array, 
not the dimensions themselves. The actual dimensions 
are declared in the REDIM statement. 


Named COMMON Blocks 


The BASIC Compiler 2.00 supports named COMMON 
blocks. Named COMMON blocks are declared by 
using the blockname option with the COMMON 
statement. Named COMMON blocks are different 
from unnamed (blank) COMMON statements—where 
blockname is not specified—in one key respect. Items 
(variables and/or arrays) in named COMMON blocks 
are not accessible to separate files that are chained 
(using the CHAIN statement) to the module in which 
they are named. Items that are declared in the named 
COMMON blocks of independent modules are 
accessible by each module if the modules communicate 
through the CALL statement. As such, named 
COMMON blocks can be used for intermodule 
communication without chaining (see the example in 
the following section ‘““One-Module Structure’’). Items 
that are listed in the blank COMMON statement (with 
no specified blockname) can be accessed by another 
chained file. 
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See the CHAIN and COMMON statements in BASIC 
Compiler 2.00 Language Reference for details on 
statement syntax. 


If the same blockname is used in more than one 
module, the items in the item lists must be the same 
type and size and listed in the same order. However, 
the names may be different. For example, the lists 
A,B,C(2) and E,F,G(2) would be valid, but E,F(2),G 
would not be valid. 


Structuring Modular Programs 


The separate compilation capability of the BASIC 
Compiler 2.00 allows a flexible environment for 
structuring large programs through the subprogram, 
module, and named COMMON block capabilities. 
These structures make it possible to construct libraries 
of compiled IBM BASIC modules, with each module 
within a library consisting of one or more subprograms. 

& Parameters passed with the CALL statement and 
named COMMON biocks provide communication 
between modules. 


Modular programming has three major benefits: 


1. Comprehensibility — Each subprogram or module 
has a specific task that it performs on a small 
number of parameters or common variables. This 
can make the overall program much easier to 
understand. 


2. Independence — Because the communication 
paths among the subprograms are isolated and 
well-defined, a given subprogram is dependent on 
another subprogram only in a controlled manner. 
This allows the subprograms to be developed 

& independently, even by different programmers. It 
also permits the reuse of subprograms across 
several related applications. 
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3. Flexibility — If the dependencies among 
subprograms are minimized, a given subprogram 
may be completely rewritten or replaced by one 
with a better algorithm—as long as its overall 
results do not change. Such “information hiding”’ 
can also enhance the overall flexibility of the 
application program by allowing it to be tailored 
for another system or user (for example, by 
recompiling a single module and relinking the 
program). 


Libraries of subprograms can be structured in two 
different ways. First, a single module can contain all 
the subprograms that together perform some set of 
functions. The second method is to use a library of 
modules where each module usually contains only one 
subprogram. In either case, each subprogram linked 
must have a unique name. If two modules are invoked 
that have a subprogram with the same name, a Linker 
error is generated. 


For details on creating library files see Appendix E in 
this manual. For details on linking library files, see the 

LINK chapter of the DOS manual. See also “Linking = 
the DEMO Program” in Chapter 3 of this manual for 
an example of linking multiple object modules. 


The two ways of structuring subprogram libraries are 
discussed below. 


One-Module Structure 


For circumstances in which all (or most) of a set of 
routines is used by an application, a one-module 
structure that contains all of the subprograms is a 
suitable approach. This method allows the application 
to pass information to the subprograms by CALL 
statement parameters or by named COMMON blocks. 
Hence, named COMMON blocks are used with this 
method to communicate only with the main module, 
rather than for intersubprogram communication. 


A potential drawback of the one-module structure is 
that referencing only one subprogram forces that 
subprogram’s entire module to be linked to the main 
module. The following example illustrates how this 
one-module approach could be used. Information is 
passed between the main module and subprograms 
using parameter passing and a named COMMON 
block. 


MAIN. BAS 


COMMON /MATRIX.FLAGS/ ERRFLG%,ERRMSG$ 


CALL MATADD2(ARRAY1(),ARRAY2(),TOTAL() ) 
IF ERRFLG% THEN PRINT "ERROR - "ERRMSG$ 


CALL MATSUB2(TOTAL(),EXPENSE() ,NEW.TOTAL() ) 
IF ERRFLG% THEN PRINT "ERROR - "ERRMSG$ 


MATRIX.BAS 


COMMON SHARED /MATRIX.FLAGS/ ERRFLG%,ERRMSG$ 
SUB MATADD2(A(),B(),C()) STATIC 


IF <CONDITION> THEN ERRFLG%=5 : 
ERRMSG$="DIMENSION 


MISMATCH" 
END SUB 
SUB MATSUB2(A(),B(),C()) STATIC 
END SUB 
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Creating A Library of Modules 
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If a more modular collection of subprograms is desired, 
a library of modules can be constructed. With this 
approach, most modules contain only one subprogram. 
The modules can then be collected together into a 
library using the Library Manager utility. (See 
Appendix E for details on how to use the Library 
Manager.) By creating a library of modules, you can 
link only the procedures that are required to complete 
your application. If subprograms within the library 
need to pass information to each other, either 
parameters or named COMMON blocks can be used. 
The following example illustrates the use of separate 
modules collected into the library MATRIX.LIB. 


MAIN.BAS 


COMMON /MATRIX.FLAGS/ ERRFLG%,ERRMSG$ 


CALL MATADD2(ARRAY1() ,ARRAY2(),TOTAL() ) 
IF ERRFLG% THEN PRINT "ERROR - "ERRMSG$ 


MATRIX.LIB contains MATADD and MATSUB. 


MATADD.BAS 


COMMON SHARED /MATRIX.FLAGS/ERRFLG%, ERRMSG$ 
SUB MATADD2(A(),B(),C()) STATIC 


IF <CONDITION> THEN ERRFLGS&=5 : 
ERRMSG$="DIMENSION 


MISMATCH" 


END SUB 
MATSUB.BAS 


COMMON SHARED /MATRIX.FLAGS/ ERRFLG%, ERRMSG$ 
SUB MATSUB2(A(),B(),C()) STATIC 


END SUB 


Calling Modules VS. Chaining Files 


YY Another method of structuring large applications into 
separate units can be performed by chaining one file to 

another with the CHAIN statement. Programs that 
access one another with the CHAIN statement are also 
separately compiled units; however, they are not linked 
with the the calling program into one load module. 
When a CHAIN statement is executed, the specified 
file is overlaid onto the same memory area that was 
occupied by the code from the calling module (that is, 
the module that contained the CHAIN statement). 
Therefore, chaining modules uses a relatively small 
amount of memory when compared to calling modules. 


When the CALL statement is used to access code in 


another module, the only requirements are to set up the 
argument list and execute the intersegment call. 
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Because the Linker has already loaded the referenced 
module into memory, no code needs to be loaded into 
memory each time a call to an external module is 
executed. In addition, each separately compiled module 
is given its own code segment of up to 64K bytes. 
These code segments immediately follow the main 
module code segment in memory in order of linking. 
Consequently, the execution speed of a modular 
application in which each each module is called is much 
faster than the execution speed of an application that is 
chained together. 


If the amount of memory in your system is sufficient to 
accommodate a one-time loading of your application, 
calling subprograms is a more efficient method of 
modularizing your application. 


Using the $MODULE Metacommand 
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The $MODULE metacommand allows you to change 
the internal module name that is passed to the Linker. 
This is useful when you want the module name to be 
different from the name of the source file. If 
$MODULE is used, it must appear before the first 
executable statement. 


Note: If all of the BASIC Compiler 2.00 modules 
linked together do not have unique module names, 
unpredictable results occur. 


All compiler-generated code for each module is placed 
in its own segment, as follows: 


Segment Alignment Class 
modnam_ CODE Paragraph BC __CODE 


Note: The segment names generated by the 
compiler have changed with this release. This 
should not affect any assembly language routines 
linked with an BASIC Compiler 2.00 application, 
but if any problems arise, consult the runtime map 
in BASIC Compiler 2.00 Language Reference. 


Calling Assembly Language 
Subprograms 


This section describes how Object modules produced 
by the IBM Personal Computer BASIC Compiler can 
be linked with object modules produced by the IBM 
Personal Computer Macro Assembler. Refer to the 
previous section ‘““Modular Programming”’ and the 
SUB/EXIT SUB statement in BASIC Compiler 2.00 
Language Reference for more information on linking 
with other BASIC subprograms. 


It is useful to call an assembly language subprogram 
from your BASIC compiled programs to communicate 
with the IBM Personal Computer DOS or ROM BIOS. 
Assembly language subprograms can also be used to 
communicate with any special hardware or adapter 
cards that you may have in your computer. 


Assembly language subprograms can be invoked from 
BASIC compiled programs through: 


e the CALL statement 

e the CALLS statement 

e the CALL ABSOLUTE statement 
e the USR function. 


Each method is described in this section. 
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The CALL statement is the recommended method for 
interfacing your assembly language subprograms. 
Interfacing with CALL produces more readable source 
code and, more importantly, allows you to pass 
parameters to your assembly language subprograms. 
The IBM Personal Computer Macro Assembler is 
required for this method. 


The following discussion assumes that you are familiar 
with the assembly language instruction set for your 
computer and the IBM Personal Computer Macro 
Assembler. 


For more information, see the CALL, CALLS, and 
CALL ABSOLUTE statements, and the USR function 
in BASIC Compiler 2.00 Language Reference. 


Structuring Your Assembly Language Program 
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Your assembly language subprogram may typically 
contain four segment definitions (SEGMENT and 
ENDS statements enclosing other statements). These 
definitions allow you to define your program code 
(CODE segment), local initialized data (CONST 
segment), local uninitialized data (DATA segment), 
and additional stack space (STACK segment). Each of 
the two segments that contain data is referenced as a 
group called the DGROUP. You can define additional 
segments for your own special needs. You can also use 
the STRUC pseudo-op of the Macro Assembler to lay 
out your formal parameters passed on the stack from 
the calling program. Each of these four segments has 
special requirements that are listed below. The 
following is a sample program structure to be invoked 
using the BASIC CALL statement. 


TITLE MYSUB 
PAGE piae 


PARMLST STRUC 

;You can put a definition of your parameter 

;list here as it appears on the stack 

SAVE BP DW ;Save contents of BP 


RET _ OFF DW © ;Return address of calling prog 
RET SEG DW r 

PARMN DW ? ;Offset from DS of nth argument 
PARM2 DW ? ;Offset from DS of 2nd argument 
PARM1 DW ? ;Offset from DS of ist argument 
PARMLST ENDS 

PARM SIZE EQU PARM1-PARMN + TYPE PARM1 


CONST SEGMENT WORD PUBLIC 'CONST' 
;Local data area for all initialized data 
;needed for your assembly language subprogram 


CR DB DH 
LF DB SAH 
CONST ENDS 


DATA SEGMENT WORD PUBLIC 'DATA' 

;Local data area for all uninitialized data 
;needed for your assembly language subprogram 
VAR 1 DB ? 

DATA ENDS 


;CONST and DATA are part of the DGROUP 
DGROUP GROUP DATA, CONST 


STACK SEGMENT WORD STACK 'STACK' 
DW N DUP(?) 


STACK ENDS 


CODE SEGMENT BYTE PUBLIC 'CODE' 
ASSUME CS:CODE,DS:DGROUP 


;Your CODE segment must contain a PROC FAR 


MYSUB PROC FAR 
PUBLIC MYSUB 
PUSH BP ;Contents of BP saved 
MOV BP,SP ;Set addressability to parms 
;Your assembler logic starts here 
MOV BX,[BP].PARM1 ;Get offset from DS of first argument 
MOV AX, [BX] ;Get the integer value at that offset 
EXIT: POP BP ;Clean up stack 
RET PARM_SIZE ;Restore the stack 
MYSUB ENDP 
CODE ENDS 
END 
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CODE Segment 


The CODE segment is the section of your assembly 
language subprogram that contains the executable 
instructions. There are several special requirements for 
constructing the CODE segment of a called assembly 
language subprogram: 


1. Your CODE segment should have a CLASS of 
‘CODE.’ 


2. Your CODE segment must contain the entry point 
as the name of a far procedure (PROC FAR). 


3. You must identify the entry point to your 
subprogram by including a PUBLIC definition. 


4. The CODE segment should follow the DATA and 
CONST segments so that it can make backward 
references to these segments. 


5. The CODE segment should be “BYTE” aligned 
after the last segment in the DGROUP. 


6. You must restore the original contents of all of the 
segment registers and the SS and SP registers 
before returning to the calling program if you have 
changed the contents of these registers. The 
BASIC Compiler makes no assumptions about the 
contents of any of the other registers. 


7. The called subprogram needs to know the number 
and length of any parameters passed. The BP 
register can be used as a pointer to reference these 
parameters on the stack. 


8. If you invoked your subprogram with the CALL 
statement, you must do a RET n (where n is two 
times the number of parameters passed to your 
subprogram) to adjust the stack to the start of the A“ 
calling sequence. 


C-22 


9. If you invoked your subprogram with the CALLS 
statement, you must do a RET n (where n is four 
times the number of parameters passed to your 
subprogram) to adjust the stack to the start of the 
calling sequence. 


DATA and CONST Segments 


If your assembly language subprogram requires data in 
addition to what was passed from the calling program, 
your subprogram must contain one or two segments 
that define these values. There are several special 
requirements for these data areas: 


1. All initialized data (data whose initial value has 
been specified) declared in your assembly language 
subprogram must be in the segment CONST, class 
‘CONST.’ 


2. All uninitialized data (data whose initial value has 
not been specified) declared in your assembly 
language subprogram should be in the segment 

& DATA, class ‘DATA.’ Uninitialized data can also 
be put in segment CONST, class ‘CONST,’ but 
this results in a slightly larger .EXE file. 


3. All data referenced in your assembly language 
subprogram should be in the group DGROUP. An 
ASSUME DS:DGROUP assembler directive may 
be used to set this up. 


4. The CONST and DATA segments should be 
“WORD?” aligned. 
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STACK Segment 


If you need to increase the default size of BASCOM’s 

stack, you can specify a larger stack with the /S 

parameter at link time, or you can include a STACK 

segment in your subprogram. If you include a stack, 

there are several special requirements for the STACK “ 
segment. 


1. Your stack segment must be named STACK and 
have a class of ‘STACK.’ 


2. Your stack should contain only uninitialized data. 


3. The STACK segment should be ““WORD” aligned. 


Receiving Control From The Caller 


The stack is the way your calling program 
communicates with your assembly language 
subprogram. The formal parameters you pass to your 
assembly language subprogram are stored on the stack. 
The BASIC compiler stores the return address code 
segment (CS) and offset (IP) of the calling program on 
the stack so that it is able to regain control when your 
subprogram is finished. Exactly what appears on the 
stack depends on the method of calling your 
subprogram (CALL or CALLS) and the type of 
parameters you are passing. 


The CALL Statement 


The CALL statement is the most common and 
recommended way of interfacing assembly language 
subprograms. For each argument in the formal 
parameter list of the CALL statement, one word (2 
bytes) is pushed onto the stack. ~ 
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This word is the offset of the argument (or descriptor in 
the case of arrays and strings) from the runtime data 
segment (DS) of BASCOM. 


The CALLS Statement 


The CALLS statement pushes 2 words (4 bytes) onto 
the stack for each argument in the formal parameter 
list. The first word pushed is the segment value of the 
runtime data segment (DS) for BASCOM, and the 
second word is the offset of the argument or descriptor 
from DS. Because of the overhead of the additional 2 
bytes for each formal parameter, CALLS is less 
desirable than CALL. CALLS is used for existing 
routines that expect both the segment and offset of 
each argument to be on the stack upon routine entry. 


Stack Diagram 

The following diagram illustrates the contents of a stack 
after an invocation of the CALL statement. The calling 
instruction from the main program is: 


CALL MASM1 (PARMA, PARMB, PARMC) 


Low Addresses 


PUSH 4 


POP + 


High Addresses 
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The stack grows from high addresses to low addresses. 
That is, as data is placed on the stack (pushed), the 
stack pointer register (SP) decreases. As data is 
removed (popped) from the stack, the stack pointer 
register (SP) increases. 


After the call, the stack pointer register (SP) points to 
the low word of the return offset on the stack. 


Parameter Addressability 


Addressability to the parameters on the stack should be 
performed through the base pointer (BP) register. The 
Basic Compiler requires, however, that the contents of 
the BP register be restored; therefore, the first 
instruction of your assembly language subprogram 
should be: 


PUSH BP 
Your next instruction should move the contents of the 


stack pointer register (SP) into the base pointer register 
(BP). This instruction is: 


MOV BP,SP 


Your formal parameters can then be referenced through 
positive offsets added to BP. For example, if your 
subprogram had executed the above instructions, and 
your next instruction is to access PARMC as it appears 
in the Stack Diagram, PARMC would be accessible as 
[BP + 6]. The offset into the stack of any one 
particular parameter is calculated as follows: 


OFFSET FROM BP = 2 * (N-M) + 6 
Where N is the total number of parameters passed and 


M is the position of the specific parameter in the formal 
parameter list. ~ 
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M may range from one to N. The offset from BP is 
calculated similarly for the CALLS statement. The 2 in 
the formula would be changed to 4. 


The STRUC pseudo-op of the Macro Assembler is a 

convenient and clear way of defining the contents of 

the stack. The following example illustrates how to 
& define a map of the stack within your subprogram: 


FRAME STRUC 
SAVE_BP DW ? ;Saved BASIC's BP 
Ret OFF DW ? suttset to RET to 
;Calling program 
RET_SEG DW ? ;segment to RET 
;to Calling program 
PARMN DW ? ;Offset of nth argument 
PARM1 DW ? ;Offset of 
sfirst argument 
FRAME ENDS 


ow Returning To The Caller 


When your assembly language subprogram returns to 
the caller, you must make sure that the BP register has 
the same value that it contained on entry to your 
subprogram. 


In the sample program discussion, because the contents 
of BP was initially saved on the stack with the PUSH 
instruction, the subprogram should restore the original 
contents of BP with the POP BP instruction before the 
return. 


Also, you must ensure that the stack is in the same state 
as it was on entry. That is, the called routine must do a 
RET n (where nv is two or four times the number of 
parameters in the formal parameter list depending on 
whether you used CALL or CALLS) to adjust the 
stack to the start of the calling sequence. 
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Based on the information provided by the STRUC in 
the previous example, you could calculate the operand 
to appear on the RET statement. By including the 
following equate in your subprogram: 


PARMSIZE EQU PARM1 - PARMN + TYPE PARMI1 


the RET statement of your subprogram would then 
appear as follows: 


RET PARMSIZE 


Additionally, if your subprogram disables interrupts, it 
should enable them prior to the return. 


The Formal Parameters 
Passing By Reference 


The formal parameters are the window the main calling 
program has to your assembly language subprogram. 
By including a result parameter in the formal parameter 
list, the subprogram is able to store the result in the 
memory location pointed to by that formal parameter. 
When you specify simple variables or array elements in 
the formal parameter list, these are passed by reference. 
This means that the subprogram can change the value 
of the variable in the calling routine by assigning a new 
value to its corresponding formal parameter in the 
subprogram. 


Argument Expressions 


Argument expressions can also be passed as arguments 
to an assembly language subprogram. An argument 
expression is any valid expression except simple 
variables and array element references. When an 
expression is encountered in the formal parameter list in a) 
a CALL or CALLS statement, the resulting value is ; 
assigned to a temporary variable of the same type. 
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This variable is then passed by reference to the 
subprogram. This permits the subprogram to read or 
even alter the value given to it, but the real value 
remains unchanged. The local copy is discarded upon 
exit from the subprogram. For example: 


CALL (5% + BY, XS? 


If a simple variable or array element is enclosed in 
parentheses, it is passed in the same way as an 
argument expression. For example: 


CALL SUBPROG(A,(B)) 


The subprogram must know the type of each argument. 
The meaning of what appears on the stack for each 
formal parameter varies according to the data type of 
the argument. The following discusses certain data 
types that should be given special consideration. 


Arrays 


If you wish to pass an entire array to your assembly 
language subprogram, you should not pass the entire 
array aS a parameter; rather, you should pass the base 
element of the array by reference (for example, 
A(0,0)). When the base of a dynamic array is passed 
to your subprogram, the offset of the array descriptor 
from the compiler’s runtime data segment (DS) is 
pushed onto the stack. Subprograms must use the 
descriptor to determine where the array is located. 


Refer to the section ““Dynamic Array Descriptors” in 
Appendix A for details on specifying dynamic array 
descriptors. 


Note: An array base argument cannot be used in a 
CALLS statement. 
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Strings 


If the argument passed is a string, the parameter’s 
offset points to 4 bytes called the “‘string descriptor.” 
For more information on string descriptors, refer to 
Appendix A. ) 


The content of strings may be altered by assembly “y 
language subprograms, but their lengths and descriptors 

must not be changed. The BASIC compiler cannot 

correctly manipulate strings if their lengths or 

descriptors are modified by external routines. 


Useful Information 


You should note the following points when coding your 
assembly language subprogram: 


e Assembly language subprograms are always 
considered FAR procedures. That is, the BASIC 
Compiler 2.00 uses a long CALL instruction to 
transfer control to your subprogram. This means 
that you must declare your assembly language ~ 
subprogram as a FAR procedure by using the 
Macro Assembler PROC statement. See the 
sample program for an example. 


e When you link your BASIC and assembly language 
modules together, the Linker tries to find a 
PUBLIC symbol that matches the subprogram 
name specified in the CALL statement or the 
CALLS statement from the BASIC program. You 
must declare the name of your assembly language 
subprograms as a PUBLIC name using the Macro 
Assembler PUBLIC directive. See the sample 
program for an example. 
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e You should link your assembly language 
subprogram after at least one object module that 
has been compiled with BASIC Compiler 2.00. An 
object module produced from BASIC Compiler 
2.00 should appear first in the object module files 
list supplied to the Linker. 


&Y e Your assembly language subprogram should 
include the definition of the segment DATA and 
the segment CONST as part of the group 
DGROUP with the following code: 


DGROUP GROUP DATA,CONST 


e The called subprogram must restore the contents 
of all of the segment registers, and the SP and BP 
registers. The BASIC Compiler 2.00 makes no 
assumptions about the contents of any of the other 
registers. 


e You should include an ASSUME statement in your 
assembly language subprogram that states that the 
CS register points to your code segment and the 
DS register points to the group DGROUP. 


Hints for Debugging an Assembly Language 
Program 


1. You can include the instruction INT 3 as the first 
executable instruction of your assembly language 
subprogram. You can then run the linked .EXE 
file under the DOS DEBUG program. A break 
point occurs at this instruction, and you can use 
the DOS DEBUG program to analyze the logic of 
your subprogram. Use the G or T options of 
DEBUG to step over the INT 3 to continue 
execution of your assembly language subprogram. 
An .EXE file with this INT 3 instruction can only 
be run under the DOS DEBUG program. 
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Note: This does not work if /V or /W are 
used because INT 3 is also used for polling for 
events such as communications activity. 


2. Before returning to the calling program, make sure 
you restore the initial values to the appropriate 
registers. Clean up any values you may have 
pushed onto the stack. Use the RET(n) assembler 
instruction to clear any parameters from the stack. 


Sample Program (BASIC) 


REM This subprogram accesses three assembly subprograms to return an array 
REM containing the names of files on a disk. 

REM It essentially does a FILES and puts the results where you can reach 
REM them. 

REM These subprograms are assembled separately and linked with the program 
REM containing this subprogram. 


REM 
REM SYNTAX: 
REM CALL DIR(filespec,string array,integer) 
REM where 
REM filespec is the name (including global characters) of the files 
REM you wish to find (it is a string). It may include a 
REM path 
REM string array is a one-dimensional array of strings where the names 
REM of any matching files are stored--left justified ina 
REM field of 12 blanks 
REM integer is an integer variable that returns the 
REM number of matching files found 
REM 
SUB DIR (PATHFILE$,FOUNDFN$(1),NFOUND%) STATIC 
POSIT = LBOUND( FOUNDFN$) "Get lower bound 
FOUNDFN$(POSIT) = SPACE$(12) "Create field of 12 blanks 
CALL FINDFIRST (PATHFILE$,FOUNDFN$(POSIT) ) "Find first matching file 


WHILE POSIT < UBOUND(FOUNDFN$) AND FOUNDFN$( POSIT) <>SPACE$(12) 
"Look for more files while there is 
"still room and we keep finding them. 


POSIT = POSIT+1 "Slot for next filename 
FOUNDFN$( POSIT) =SPACE$(12) "Create field of 12 blanks 
CALL FINDNEXT(FOUNDFN$(POSIT) ) "Find the next matching file 
WEND 
NFOUND%=POSIT-LBOUND( FOUNDFNS$ ) 'Figure out how many files were found 


IF POSIT=UBOUND(FOUNDFN$) THEN NFOUND%=NFOUND%+1 
"Special case--more files than space 
‘in the array 

IF FOUNDFN$(LBOUND(FOUNDFN$) )=SPACE$(12) THEN NFOUND%=8 
"Special case--no matching files were 
"found 

CALL RESTOREDTA "Clean up 


END SUB 
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Sample Program (ASM) 


TITLE FILES 

PAGE BES Se 

COMMENT ; 
These three assembly language subprograms link with a program 
containing the BASIC subprogram DIR to provide easy access to 
the names of disk files. They perform essentially the same 
function as the FILES statement, but return the directory in 
an array as opposed to on the screen. 


PARAMLIST STRUC 

;List of parameters as they appear on the stack 

SAVE_BP DW ? ;Retain contents of BP 

RET OFF DW ry ;Return address of calling program 

RET SEG DW £ 

PARM2 1 DW ? ;Of the three subroutines below, one has 


;two parameters, one has one parameter, and 
;the other has no parameters. For the 
;subroutine with two parameters, this field 
;addresses the second parameter, for the 
;subroutine with one parameter, this field 
;addresses it and the field PARM1 below is 
;not used. 

PARM1 DW ? ;Address of first parameter in list (for the 
;subroutine with two parameters 

PARAMLIST ENDS 


PARM SIZE1 EQU OFFSET PARM2_1 - OFFSET RET SEG 
;Size of parameter block for subroutine 
;With one parameter 

PARM SIZE2 EQU OFFSET PARM1 - OFFSET RET SEG 
;Size of parameter block for subroutine 
;With two parameters 


CONST SEGMENT WORD PUBLIC 'CONST' 
;Local data area for initialized data 

;No constants 

CONST ENDS 
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DATA SEGMENT WORD PUBLIC 'DATA' 
;Local data area for uninitialized data 


SAVE DTA_OFF DW ? ;Address of current DTA 

SAVE DTA_SEG DW ? 

DTA DB 36 DUP(?) ;Working DTA 

FILENAME DB 13 DUP(?) ;Found filename 

PATHFILE DB 64 DUP(?) ;Path and filename for search 
DATA ENDS 


;CONST and DATA are part of the DGROUP 


DGROUP GROUP DATA, CONST 
STACK SEGMENT WORD STACK 'STACK' 
DW 2 DUP(?) ;These subroutines push up to 
;two items on the stack at any 
;gGiven time 
STACK ENDS 
CODE SEGMENT BYTE PUBLIC 'CODE' 


ASSUME CS:CODE,DS:DGROUP 
;All three procedures are of type FAR 


FINDFIRST PROC FAR ;This procedure finds the first 
;matching file 
PUBLIC FINDFIRST 


PUSH BP ;Contents of BP saved 

MOV BP,SP ;Set addressability to parms 

MOV BX, [BP] . PARM1 ;Get offset into DS of first parm 
MOV CX, [BX] ;Get the size of the string 

MOV Si, teats) ;Get the address of the string 
PUSH DS *ES=DS for string move 

POP ES 

LEA DI, PATHFILE ;Move path/file specification to 
REP MOVSB ;the location PATHFILE 

MOV AH, 2FH *Get the current DTA 

INT 21H 

Jc EXIT1 

MOV SAVE DTA_OFF,BX ;Save the DTA--we're using our own. 
MOV SAVE DTA_SEG,ES 

LEA DX,DTA ;Set the DTA 

MOV AH, 1AH 

INT 21H 

JC EXIT1 

LEA DX, PATHFILE ;Find the first file that matches 
MOV AH, 4EH ;the path/filename given 

INT 21H 

Jc EXIT1 

MOV BX,[BP].PARM2 1 ;Get offset of second parameter 
MOV DI, [BX+2] ;Get address of string 

LEA SI,F ILENAME ;Address of found filename 

PUSH DS ;ES=DS for string move 

POP ES 
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LOOP 1: 


EXIT1: 


FINDFIRST 


FINDNEXT 


LOOP2: 


EXIT2: 


FINDNEXT 


RESTOREDTA 


RESTOREDTA 


CODE 


LODSB 
CMP 
JE 
STOSB 
JMP 


POP 
RET 


ENDP 


PROC 


PUBLIC 
PUSH 
MOV 


MOV 
INT 
JC 


MOV 
MOV 
LEA 
PUSH 
POP 


LODSB 
CMP 
JE 
STOSB 
JMP 


POP 
RET 
ENDP 


PROC 


PUBLIC 
PUSH 


MOV 
MOV 
MOV 
INT 


POP 
RET 
ENDP 


ENDS 
END 


AL,@ 
EXIT! 


LOOP 1 


BP 
PARM SIZE2 


FAR 


FINDNEXT 
BP 
BP,SP 


AH, 4FH 
21H 
EXIT2 


BX,[BP].PARM2_ 1 
DI, [BX+2] 

SI, FILENAME 

DS 

ES 


AL, 6 

EXIT2 

LOOP2 

BP 

PARM SIZE1 

FAR 

RESTOREDTA 

Ds 
DS,SAVE_DTA_SEG 
DX,SAVE DTA OFF 
AH, 1AH 


21H 


DS 


;Get character of filename 
;Check for end of filename 
;If end then stop 

;Else copy character 

;and keep copying 


;Restore the base pointer 
;Restore the stack and return 


;This procedure finds the name 
;0f subsequent matching files 


;Contents of BP saved 
;Set addressability to parms 


;Find next matching file 


;Get offset into DS of first parm 
;Get address of the string 
;Address of found file 

;ES=DS for string move 


;Loop to copy found filename 
;Check for end of name 

;If end then stop 

;Else copy the character 
;and keep copying 


;Restore base pointer 


;Restore the stack and return 


;This procedure restores the 
;DTA that was set in FINDFIRST 
;so BASIC won't gag 

;Save DS 


;Fetch the DTA we saved in FINDFIRST 


;Restore the DTA 


;Restore DS 
;Return 
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Other Interface Methods 


The following BASIC compiler statements and 
functions provide additional methods for invoking 
assembly language subprograms from your BASIC 
compiled program. 


CALL ABSOLUTE Statement “yy 
USR Function. 


The CALL ABSOLUTE statement works similarly to 
the BASIC Interpreter CALL statement. It allows you 
to call subroutines which you may have POKEd or 
loaded into a memory area with the BLOAD command. 
For assembly language subprograms not easily adapted 
to the BASIC compiler environment, this interface may 
provide a way for you to transport your program from 
the BASIC Interpreter. 


The USR function allows assembly language 
subprograms to be called in the same way intrinsic 
functions are called; however, there is no way to pass 
parameters except by using POKE statements to 
protected memory locations. 


Getting the Subroutine into Memory 


Getting the subroutine into memory is the most 
complicated part of using these interface methods. 
Also, you must store the subroutine in a stable memory 
area to prevent destroying vital data for the BASIC 
Compiler. Based on these considerations, storing the 
subroutine in a static integer array is the safest method. 
For long subroutines, it is convenient to include a 
special header in the file which the BLOAD command 
can recognize. The BLOAD command can then be 
used to get the subroutine into the array. Short 
subroutines can easily be poked or simply assigned to 
the array elements. The following discussion explains 
each method and provides examples. 
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BLOADing the Subroutine from a File 


You use the BASIC BLOAD command to load a 

memory image file directly into memory. The file is an 

assembly language subroutine that was assembled with 

a BLOAD header, linked and converted to a .BIN file 

using EXE2BIN. See Disk Operating System (the DOS 
& manual) for information on the EXE2BIN utility. 


Considerations 


e An assembler is necessary in order to use this 
method. 


e For an assembly language subroutine to be 
BLOADed into memory, it must appear to have 
been created by BSAVE. This is done by including 
a 7-byte BLOAD header that is linked as the first 
segment of the subroutine. These 7 bytes function 
as a loader that BLOAD looks at and then 
discards. The beginning of your routine in memory 

Y is the first byte following this header. 


The example that follows shows how a subroutine is 
BLOADed into an integer array and then is called from 
the BASIC compiled application. The subroutine adds 
the contents of the first and second parameters and 
puts the result into the third parameter. 


A step-by-step explanation of the procedure follows. 
1. Assemble and link your subroutine. 

2. Convert the file to a .BIN file via EXE2BIN. 

3. Inthe BASIC compiled program, dimension an 


integer array to the size needed. (Remember, size 
of the array subscript is 1/2 the number of bytes in 


& your subroutine. ) 
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4. Obtain the offset of the array within the BASIC 
compiled program’s data space using the VARPTR 
function. 


5. BLOAD the subroutine into the array. 


6. Using the CALL ABSOLUTE statement, invoke 
the subroutine. 


A Sample Subroutine 


C-38 


The function of this subroutine is to add the contents of 
the first and second parameters and put the result into 
the third parameter. The sample subroutine is invoked 
by the CALL ABSOLUTE statement. Parameter 
passing is done by putting variable names in the 
parenthesized list in the CALL ABSOLUTE statement. 


The comments inserted in the program listing are 
intended to help you understand the most important 
points of the operation and structure of this subroutine. 
A more detailed analysis follows the listing. 


TITLE SUB 1 


PARM STRUC ;Description of parameter list 
SAVEBP DW 6 ;Saves BASIC's BP register 
RETOFF DW 6 ;Offset for the return 
RETSEG DW 6 ;Segment for the return 
PARMC DW 6 ;Offset to third parameter 
PARMB DW 6 ;Offset to second parameter 
PARMA DW 6 ;Offset to first parameter 
PARM ENDS 
AAAA SEGMENT PARA 

DB OFDH ;BLOAD ID 

DW 6,6 

DW TRAILER-HEADER ;Module size 
AAAA ENDS 


BASDATSEG SEGMENT BYTE PUBLIC 'CODE' 
ASSUME CS:BASDATSEG,DS:BASDATSEG 


HEADER EQU $ ;Start of memory image 


SUBRT PROC FAR 

NOP ;For debugging, can be 
; replaced by CCH (INT 3) 
; which is the DEBUG 


; breakpoint 
PUSH BP ;Save BASIC's BP register 
MOV BP,SP ;Set addressability to 

; parm area on stack 
MOV SI, [BP] .PARMA ;Get offset to parm! 
MOV AX, [STI] ;Get value of parmt 
MOV SI,[BP].PARMB ;Get offset to parm2 
ADD AX, [SI] ;Add value of parm2 to acc 
MOV DI,[BP]).PARMC ;Get offset to parm3 
MOV [DI] ,AX ;Pass result to parm3 
POP BP ;Restore BASIC's BP 
RET 6 ;Return to BASIC, 


. throwing away the 3 parms 
SUBRT ENDP 


TRAILER EQU $ ;End of memory image 
BASDATSEG ENDS 
END 


Sample Subroutine Explanation 


This example generates a header that looks as if it were 
created by BSAVE. It must be linked to the beginning 

of the load module by using a segment name that comes 
first alphabetically. 
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AAAA SEGMENT PARA 


DB QFDH ;BLOAD id 

DW 9 0 

DW TRAILER-HEADER 3;Module size 
AAAA ENDS 

PAGE 


This value for module size, divided by 2, is the value to “& 
be substituted for N in the BASIC program. 


The BYTE alignment of the CODE SEGMENT 
statement is needed so the memory image will be loaded 
as the next byte following the dummy BLOAD header 
with no alignment padding bytes in between. 


BASDATSEG SEGMENT BYTE PUBLIC ‘CODE’ 


This code is to be loaded into a BASIC integer array in 
the BASIC Compiler’s data segment. The offsets 
shown by the assembler listing are relative to the start 
of the subroutine, not to the start of the BASIC 
Compiler’s data segment. 


conventions required by the CALL and CALLS 
statements. This is not necessary since your 
subroutine is not going to link with the calling 
program. 


Note: The segment names do not conform to the a“ 


The BASIC Compiler main program would contain the 
following statements: 


OPTION BASE 1 

DIM ARRAY%(12) 

‘Find start of array 
SUBRT%=VARPTR(ARRAY%(1) ) 
‘Load routine into array 
BLOAD "SUB1.COM", SUBRT% 
‘Pass parms to subroutine 
PARMA% = 2: PARMB% = 3 
‘Locate subroutine 

‘Parms in CALL ABSOLUTE “ 
CALL ABSOLUTE(PARMA%, PARMB%, PARMC%, SUBRT%) 

‘Display results 

PRINT PARMC% 
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Assigning a Subroutine into Memory 


This is the procedure you use to assign machine code to 
an integer array with simple assignment statements and 
invoke the subroutine: 


L 


Determine the machine code for your subroutine. 
See ‘“‘DEBUG” in Disk Operating System (DOS) 
manual under the ‘““Assemble”’ option. 


Dimension an integer array to the size you need. 
Remember, an integer uses 2 bytes of memory, so 
the size of your array is one-half the number of 
bytes in your subroutine. 


There are several reasons for using an integer array 
(2 bytes per element) instead of a single-precision 
(4 bytes per element) or a double-precision array 
(8 bytes per element). When you assign the 
subroutine to an integer array, you never leave 
more than 1 byte of memory unused; witha 
double-precision array, you could waste 7 bytes. A 
fundamental reason for the integer array method is 
that you perform WORD assignment to the array 
elements rather than byte assignment, and a 
WORD happens to be 2 bytes. It would be easy to 
make a mistake if you were assigning four words to 
each array element since the CPU in the system 
expects to see the machine code in a low-byte, 
high-byte format. The example that follows shows 
how the machine code in the assignment 
statements is switched from the order of the bytes 
as they would appear in the assembled listing. 


Assign the machine language code to the array 
elements, one word at atime. Remember that 
your system reads bytes expecting the low byte 
first, so store your data low-byte, high-byte. 
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4. Determine the offset of the subroutine within 
BASIC’s data segment by using the VARPTR 
function. 


5. Invoke the subroutine. This example illustrates the 
use of the USR function. 


Example: & 


DEFINT A-Z: OPTION BASE 1: DIM ARRAY (3) 


DATA &HCD55 >REM 55H Push BP 

DATA &H5D@5 >REM CD@5H INT 5 
REM 5DH POP BP 

DATA &H9QCB :REM 99H NOP 


FOR I = 1 TO 3: READ ARRAY(I): NEXT I 
PRINT "This is an example of how " 
PRINT “a BASIC routine can cause " 
PRINT "a hard copy to be dumped " 
PRINT "to a printer by using the 
PRINT "shift-print screen function 
PRINT "called via an assembly language 
PRINT “subroutine that is built into " 
PRINT “a BASIC integer array" 

DEF USR@ = VARPTR(ARRAY(1)) 

Y = USR@(X) 


Notice that the data statement reads data into the 
array a WORD at atime. The assembled listing would 
list the bytes in the order that they appear in the 
commented section of the program, yet the program 
switches the order of the bytes in the words as they _ 
are assigned to the array elements since the format of 
a word is low-byte, high-byte. 
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Poking a Subroutine into Memory 


This next example uses the same assembly language 

subroutine, but the BASIC POKE statement is used to 

POKE the bytes into the array. The POKE statement 

takes care of the byte order for you, so you do not 

have to reverse the order of the bytes as they would 
YY appear in an assembled listing. 


DEFINT A-Z:OPTION BASE 1 
DIM ARRAY (3) 


DATA &H55 >REM 55H Push BP 
DATA &HCD, &H@5 >REM CD@5H INT 5 
DATA &H5D :REM 5DH POP BP 
DATA &HCB >REM CBH RET FAR 
P=VARPTR(ARRAY (1) ) 

FOR I=@ TO 4 

READ J: POKE(P+I) ,J 

NEXT I 


PRINT "This is an example of how 

PRINT "a BASIC routine can cause 

PRINT "a hard copy to be dumped " 

PRINT “to a printer by using the 

PRINT "“shift-print screen function 
Yy PRINT “called via an assembly language " 

PRINT “subroutine that is built into " 

PRINT "a BASIC integer array" 

DEF USR@ = P 

Y = USR@(X) 
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Appendix D. Using IBM Personal 
Computer ISAM Files 


The Indexed Sequential Access Method (ISAM) is a 
library of subroutines that allows access to files both 
sequentially and by index. The files used with ISAM 
have a special format. 


Normally, BASIC supports two types of data files; 
sequential files and random access files. These two 
types are sufficient for most applications. The major 
limitation of these two file types, however, is that they do 
not allow you to access the records in the file according 
to their content. You must either search the entire file 
until the desired record is found, or, you must know 
the number of the desired record. 


With the addition of ISAM, you can access data based 

YY on the content of your records. If, for example, you 
want to read the record that contains information 
about product number 34056-J, delete any records 
with information on employee T. R. James, or update 
the record containing information on the price and 
availability of marble, ISAM provides a fast way to do 
SO. 


Before discussing ISAM in detail, a few basic terms 
need to be defined. 


DATA TYPE A data type is the type of value that 
is stored in a particular variable. 
BASIC ISAM supports five data 
types: integer, string, numeric, 
single-precision, and 


YY double-precision. 


DATA RECORD A data record is the basic unit of 


FIELD 


KEY FIELD 


KEY VALUE 


data in an ISAM file. Most ISAM 
subroutines operate on one record 
at a time. Generally, there will be a 
record in your ISAM file for each 
employee, spare part, or whatever 
you are storing information on. An 
ISAM file can contain any number 
of records. 


A field is part of a data record. It 
contains a single value of a 
particular data type. For example, 
an ISAM file may contain records 
that are composed of fields for 
name, address and phone number. A 
data record can consist of any 
number of fields. 


A key field is a special kind of field. 
It contains the value that ISAM 
uses to determine where a record 
goes in the file. 


A key value is the value stored in a 
key field. For example, the key 
field might be 20 bytes reserved for 
employee name, and the name stored 
there may be John Doe. John Doe 
is the key value for that key field. 


Each ISAM file is physically two files: a data file and 
a key file. A key is a data field that has been 
identified and described to ISAM. Using ISAM, you 
can access records in the data file according to the 
value contained in the key field. Both files must be 
present to use ISAM. 


File names cannot exceed 8 characters. 
Conventionally, data file names end with a .DAT 
extension and key file names end with a .KEY 
extension. 


The data file consists of data records and, usually, a 
data dictionary. The data dictionary, which resides at 
the beginning of the data file, contains binary 
descriptions of records in the file. Whenever you 
create an ISAM file, you give ISAM information about 
how your data is formatted, such as where data fields 
start and end, what type of data is contained in a field, 
and if it is acceptable to have the same value in a given 
field of more than one record. This information is 
stored in the data dictionary. 


The key file contains the indexing information that 
ISAM uses to access the data in the data file. ISAM 
gets this information (where the fields are, what type 
of data they contain) from the data dictionary, in the 
data file. The indexing is in the form of B-trees. 
B-trees are a special kind of index that point to the 
records in the data file. There is one tree in the key 
file for each key that you specify. 


Whenever you access an ISAM file, ISAM 
automatically obtains the information it needs from 
each file. For example, when you write a record to an 
ISAM file, ISAM writes the data record to the data file 
and the key information to the key file. 


It is a good idea to choose the key for a file such that 
the value of that key is unique for each record in the 
file. This may help to avoid any confusion when 
searching the records in the file for a particular key 
value. For example, social security number is a good 
field to use as a key because everyone has a unique 
social security number. 


There is a special type of key, called a split key, that 
contains more than one field. Components of a split 
key can be adjacent or nonadjacent fields, of the same 
or different data types, and may or may not be keys 
themselves. Split keys are explained further in the 
“Split Keys” section later in this appendix. 


There are two types of ISAM data records: 
nonsegmented and segmented. Record types cannot 
be mixed in one file. 


Nonsegmented records are the type most often used. 
They contain key fields that have fixed sizes. They 
may, however, contain one field that is variable in 
length, as long as that field is the last field in the 
record. 


The second type of record, called a segmented record, 
supports key fields that can vary in size. Segmented 
records are usually used to contain variable-length 
Strings. 


You can use variable length strings without using 
segmented records, by setting the length of your string 
field long enough to hold the longest string that you 
are using. 


Note: It is strongly recommended that you use 
segmented records only if it is very important to 
minimize the amount of storage space used for 
variable-length fields. 


Segmented records are further described in the 
‘Segmented Records”’ section later in this appendix. 


Writing an ISAM Application 


The ISAM interface has been designed to make access 
to ISAM files as simple as possible. In general, ISAM 
file access is similar to random I/O procedures. 
Specific ISAM subroutines are called to open and 
close ISAM files, to find records within a file, and to 
read, write, delete, or rewrite data. 


Note: The demonstration program included on 
your ISAM diskette, MAIL.BAS, is designed as 
an aid in developing your own ISAM programs. 


There are six basic steps in creating and using ISAM 
files: 


& 1. Install ISAM.EXE in memory. 
2. Open an ISAM file. 
3. Seek to (search for) some location in the file. 
4. Operate on the data. 
5. Check the results. 
6. Close the ISAM file. 


The following sections briefly describe each step. 
Detailed information on each ISAM subroutine 
appears later in this appendix. 


Ne Installing ISAM.EXE 


ISAM.EXE is a file containing the assembly language 
subroutines that make up ISAM. It must be loaded 
into memory before you can call any ISAM 
subroutines. If you try to use any ISAM subroutine 
and ISAM is not loaded, an error code of 27 is 
returned. 


To install ISAM in memory, enter: 

ISAM 

The following message appears on the screen: 
© Installing IBM Personal Computer ISAM 


(C)Copyright IBM Corp 1984, 1985 Version 2.00 
(C)Copyright Microsoft Corp 1984, 1985 


Because the ISAM routines take up memory space, 
you may want to remove them from memory when 
your program is finished. To do this, enter: 


ISAM /F 
No message appears when ISAM is removed. 


You can also control the amount of buffer space that 
the ISAM routines can use while your program is 
running. To do this, entering the following when you 
install ISAM: 


ISAM /S:xXXXXxX 


XXXXX is the number of bytes of buffer space to 
be allocated. This number can range from 
10000 to 65536. 


If you do not use the /S option or you specify a 
number less than 10000, the buffer space defaults to 
10000. ISAM performance improves as buffer space 
increases; however, this decreases the amount of 
memory available to your BASIC compiled program. 


Opening a File 


Before reading or writing to an existing ISAM file, or 
to create a new ISAM file, you must open the file. 
The ISAM subroutine IOPEN is used to open files. 
See the IOPEN statement later in this appendix for 
more details on opening ISAM files. 


Seeking a Record 


Because ISAM can only operate on one record at a 
time, you must set the current record to some record 
in the file. 


The current record is generally the record pointed to 
by the last ISEEK. (Certain other subroutines, such 
as IWRITE, INEXT, and IPREV, can also change 
what record is the current record.) 


For any specified key, the ISAM subroutine ISEEK 
can find the first record, the last record, the first 

& record with a key value equal to a specified value, or 
the first record with a key value greater than a 
specified value. 


Two other subroutines that are useful for finding a 
location in a file are ISAVEFP and IRESTOREFP. 
With these routines, you can mark and return to any 
specified file position. 


Operating on a Record 


ISAM can read or write a record, rewrite or delete a 
record, locate a related record, or find the size of a 
record. The following list describes these operations 


briefly. 
we s Read a record 


Once the current record has been established, 
often by ISEEK, that data record can be retrieved 
by IREAD. 


e Write a record 
To insert a record into the data file, use IWRITE. 
The newly inserted record becomes the current 
record. 

« Rewrite a record 
The IREWRITE procedure differs from IWRITE 


Y in that it deletes the current record from the data 
file and inserts the modified record. 


The keys are updated to reflect this change. The 
modified record becomes the new current record. 


° Delete a record 


Removing a record from the data file is done by 
establishing the current record and using 
IDELETE. The next record then becomes the 
current record. 


¢ Move to the next or previous record 


The data file can be examined sequentially by 
using INEXT and IPREV. The records are 
ordered (alphabetically or numerically) by the 
value in the key field that was used in the last 
seek operation. The record that you seek 
becomes the current record. 


* Find the size of a record 


ISIZEOF finds the size of the current record, in 
bytes. This can be useful when using 
variable-length records; to set the size of a 
buffer, for example, before reading a 
variable-length record into it. 


For complete information on all ISAM subroutines, 
see “ISAM Subroutines”’ later in this appendix. 


Checking the Results 


Status Errors 


You may encounter nonfatal errors while accessing 
your ISAM file. For example, you may try to write a 
record to an ISAM file that is not open. These less 
serious errors do not cause any messages to be 
displayed on the screen. Instead, an error code is 


returned to your program in the status variable ixstat. a 


You should code your program to check ixstat after 
each ISAM subroutine call to determine if the routine 
completed successfully. If no error occurred, ixstat = 
0. For example, after you attempt to open a file, you 
could check ixstat with the following statement: 


IF IXSTAT<>@ THEN PRINT "OPEN FAILED-CODE" ; IXSTAT 


A list of the ixstat codes and their meanings appears 
later in this appendix under “‘Status Indicators.”’ 


I/O Errors 


The variable iostat is used to check for serious I/O 
errors that may occur in your program. You may get 
an error because a drive door is open or because the 
disk you are writing to is write-protected, for example. 
Once an error occurs, it is not possible to determine 
whether it originated in the BASIC Compiler, or in 
ISAM. 


Therefore, when a serious error occurs, ISAM enters 
an interactive mode, and the following message is 
printed: 


Critical error while in ISAM: <error message> 
Abort or retry? 


If you abort and no error trapping is set, this stops 
your program. Even if the error is trapped, any 
further calls to ISAM return ixstat = 26. In either 
case, you have to rebuild any ISAM files that were 
open for updating. 


You can also try to correct the problem, (by removing 
the write-protect tab, for example), and retry. If you 
cannot correct the problem, ISAM aborts. 


You can use the value of the variable iostat to help 
determine the cause of the error. Anytime iostat is not 
equal to zero, a serious I/O error has occurred. These 
iostat values range from 1 to 13 and are set according 
to the following table. 


IOSTAT 

1 70 
- 68 
3 at 
+ HY 
5 57 
6 a9 
7 ay 


BASIC 
Error Code 


DOS Error 


Attempt to write on 
write-protected disk 


Unknown unit 


Drive not ready 


Device not ready 


Data error 


Bad structure length 


Seek error 


Message 
on 


Screen 


Permission 
denied 


Device 
unavailable 


Disk 
not 
ready 


Device 
I/O 
error 


Device 
I/O 
error 


Device 
I/O 
error 


Device 
I/O 


error 


IOSTAT BASIC DOS Error Message 
Error Code on 
Screen 


8 te Unknown media type Disk 
media 
error 


9 Ss; Sector not found Device 
I/O 
error 


10 me Printer out of paper Out 
of 
paper 


11 25 Read fault Device 
fault 


12 57 Write fault Device 
I/O 
error 


w 13 = | General failure Device 
I/O 
error 


Closing a File 


It is important to close every ISAM file that you open, 

using ICLOSE. If an ISAM file is not closed by 

ICLOSE, its key file may be corrupted. In this case, 

you must use the REBUILD utility to insure that the 

key file is valid. REBUILD is an ISAM application *) 
program that is included in your ISAM package. Its 

primary use is in building key files. See “ISAM 

Rebuild Utility” later in this appendix for more 

information. 


Other ISAM Subroutines 


The other four ISAM subroutines are: 
e IGETDP 
Gets a pointer to a record. 


e IDREAD 


Reads a record. The difference between ~ 
IDREAD and IREAD is that you give IDREAD a 

pointer to the record you want read. IREAD 

reads the current record. IDREAD can also use 

the tag file generated by IBM Personal Computer 

SORT Version 1.00 to read a data file directly. 


« IGETKD 
Gets the key description. 


e ICONTROL 


Performs a checkpoint function. 


ISAM Terms and Concepts 


This section explains some of the terms and concepts 
used in ISAM. 


ww File Handles 


The file handle is a number used by ISAM to refer to a 
specific ISAM file. Although an ISAM file is 
physically two files, (a data file, and a key file), there 
is only one file handle for each data file/key file pair. 
ISAM returns the file handle each time you open a 
file. 


Data Records 


ISAM files are similar, in some ways, to BASIC 
random files. 


YY When using random files in BASIC, the FIELD 
statement is used to allocate buffer space for the 
output data. This data buffer contains the variables 
that make up the data records in the file. For 
example: 


FIELD #1, 18 AS NAME$, 25 AS ADDR$ 


This establishes a data buffer of 35 bytes, 10 for 
NAMES$ and 25 for ADDR$. Because the space for 
this data buffer is allocated at compile time, NAME$ 
and ADDRS$ are stored consecutively in memory. 


To write a record to the file, you store the proper 

values into NAME$ and ADDR$, (using LSET and 

RSET), and write the buffer to the file. To write 
Y another record, you change the values in the data 


buffer and write it out again to the file. 


When using ISAM files, you must also establish a data 
buffer. Two methods are given here to accomplish 
this: 


e Using the FIELD statement 


e Using the COMMON statement. ‘o) 


Using the FIELD Statement 


One way to do it is with the FIELD statement. For 
example: 


OPEN "NUL" AS #9 LEN=35 
FIELD #9, 18 AS NAME$, 25 AS ADDR$ 


The above example establishes the same buffer for an 
ISAM file. The OPEN statement is necessary because 
a file must be open before you can allocate the data 
buffer with the field statement. The file is opened as 
NUL because the buffer is written to the ISAM file, 
not the BASIC file. 


To get the pointer to this data record, you can use the 
following procedure: 


1. Insert the following function definition into your 
program. 


DEF FNSADD! (VPTR) 
FNSADD! =PEEK(VPTR+3)*256.@ + PEEK(VPTR+2) 
END DEF 


This function accepts the pointer to a string 
descriptor as input and returns the address of the 
string. You must include this function in your 
program if you use the FIELD statement to 
establish the data buffer. 


2. Execute the following: 


PDATREC!=FNSADD! (VARPTR(NAME$ ) ) 


This places the address of the data record into 
PDATREC!. 


Using the COMMON Statement 


If your data record contains only numerical values, 
you can establish the data buffer using a COMMON 
statement. For example, if the data record consists of 
IDNUM and PHONENUM!, the following statement 
establishes the data buffer: 


COMMON /DATA.REC/IDNUM,PHONENUM! 


Once this is done, you can get a pointer to the data 
record with the following: 


PDATREC!=VARPTR( IDNUM) 


Note: Remember, you can us this form only if 
your data record consists solely of numerical 
values. 


Key Handles 


The key handle is a number used by ISAM to refer to 
a specific key in an ISAM file. The key handle is 
assigned by the programmer in the field description 
when the ISAM file is created. 


Key handle values range from 1 to n, where n is the 
number of keys. There does not have to be any 
physical relationship between the key handle values 
and the record layout, but it is a good idea to assign 
key values from the lowest to highest part of the 
record. 


Split Keys 


A split key is a key that is made up of more than one 
field. The component fields of a split key may or may 
not be adjacent, may be the same or different data 
types, and may be nonkey fields, keys, or split keys. 
All the components of one split key must have the 
same key handle. 


If a component field of a split key is also a key, that 
field’s description must be given twice: once to 
describe it as a key field, and once to group it with the 
other components of the split key. This type of field 
also has more than one key handle: one handle of its 
own, and one handle that is the same as the other 
components of the split key. 


When key values are compared (to determine the 
order of records, or to determine if values are equal), 
the split key components are compared according to 
the order in which they were declared in the key 
description. If the two components have equal values, 
the next component in the split key is compared. This 
is repeated until a difference is found. 


Split keys cannot be used with segmented records. 


Segmented Records 


ISAM data files contain either segmented or 
nonsegmented records. These record types cannot be 
mixed in one file. 


The address of a Key field is given by a segment 
number and an offset. For nonsegmented records, the 
segment number is 1. In segmented records, the 
segment number acts as an index to a segment table, 
which must be inserted in front of each record. The 
segment table is an array of 16-bit offsets; this offset 
is the number of bytes from the start of the record to 
the start of the segment. 


For a given key n, the address of the key is the address 
in the nth entry in the segment table, plus any offset 
within the segment itself. A field length of zero 
indicates that the field length equals the length of the 
entire segment. 


The number of segments, the segment table, and 
offsets within segments must be supplied in the record 
and field descriptions when the file is created. The 
segment table must be maintained by the application 
programmer. For this reason, it is strongly 
recommended that segmented records be used only if 
variable-length key fields are needed. Often, all 
fixed-size record fields are placed in the first segment, 
and each variable-length string field is placed in its 
own segment. The following diagram illustrates a 
3-segment record with 3 keys: 


e Key 1 is fixed-length, begins at offset 10 into the 
segment with a length of 4. 


e Key 2 is in segment 2, begins at offset O and 
occupies the entire segment. 


e Key 3 is in segment 3, begins at offset 0 and 
occupies the entire length of the segment. 


Segment Table 


Segment #1 


Segment #2 


Segment #3 


If a data file contains segmented records, it is not 
necessary for each record to contain the same number 
of segments. All segments that contain keys, however, 

must be present in each record. If a segment that ~ 
contains a key is missing from a record, the status 
code, ixstat = 10 (key not found), is returned. 


Segmented records cannot contain split keys. 


Record Description 


The record description tells how many keys are in the 
record, if the record is segmented or nonsegmented, 
and the minimum record allocation. This information 
is given to ISAM as the array “‘Rdes.”’ 


Rdes(1) = number of fields 
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The number of fields declared in the field descriptor 
array. 


Note: This includes both key and nonkey fields 
and components of split keys. 


Rdes(2) = segment-flag 


If the record is nonsegmented, segment-flag =O. If the 
record is segmented, segment-flag =1. 


Rdes(3) = minimum record allocation 


If Rdes(3) = O, then the minimum record allocation 
defaults to 8 bytes: 5 bytes of data and 3 bytes 
overhead. 


When a record is rewritten over a record that is too 
small to contain the new record, ISAM makes the old 
record into an “‘indirection record.”’ The indirection 
record points to the location of the new, larger record. 
By using indirection records, ISAM avoids having to 
change every key that pointed to the old record 
location. To make sure that every record is big 
enough to hold an indirection record, the minimum 
record allocation defaults to 8 bytes. 


Field Description 


Whenever you create an ISAM file, you must describe 
each key field that you are using; this is the 
information used to build key files. You can also 
describe nonkey fields. ISAM puts this information in 
the data dictionary, at the beginning of the data file. 
Whenever a file is opened, its data dictionary is loaded 
into memory from the data file. 


If you are using files created by IBM Personal 
Computer SORT Version 1.00, you should be aware 
that some of these files do not have a data dictionary. 
When using these files, you must specify the field 
description each time you open the file. 


It is recommended that you describe each field in the 
record when you create an ISAM file. This provides 
an easy way to identify each file and its contents. 
Complete field descriptions can also be used by other 
utilities to access field information. 


Creating A Key Descriptor ‘o) 


Field descriptions are given to ISAM as a nine-integer 
array, ‘“Kdes.”’ The parameters that you must supply 
for each field you describe are explained below. 


Kdes(1) = pointer-to-field-name 


A pointer to a buffer that contains the name of the 
field. The field name must be less than or equal to 40 
characters. If no field name is supplied, this pointer 
must be null. Field names can be used by utilities, 
such as general file dump utilities, to access fields in a 
data file. 


Kdes(2) = 0 


A reserved word area. It must be initialized to zero. 
Kdes(3) = data-type 


The data type of the field. The data type is set by 
supplying one of the following words: INTEGER, 
STRING, NUMERIC, SINGLE, DOUBLE. 


Note: You must use the $INCLUDE 
metacommand to include the file ISAM.INC in 
your program to set these values. Once this file is 
included, you can set Kdes(3) as in the following 
example: 


KDES(3) = INTEGER 


Kdes(4) = segment-number 
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The number of the segment containing the field. For 
nonsegmented records, this number is always 1. 


Segments are numbered from 1 to n where n is the 
number of segments. Segment 1 is the first segment in 
the record and segment n is the last. Each segment 
can contain many fields but no field can span more 
than one segment. 


Kdes(5) = field-position 


This is the position from the beginning of the segment 
to the beginning of the key field (the offset of the field 
in the segment). The first byte in the segment is 
numbered 1. 


Together Kdes(4) and Kdes(5) comprise the field 
address. 


Kdes(6) = field-length 


The length of the field in bytes. A zero length field 
indicates that the field size is from the field segment 

YY position to the end of the segment. If the field length 
is variable, this number should always be zero. 


Kdes(7) = key-handle 


Any value between 1 and n where n is the number of 
keys. The convention is to assign key handles 
beginning with 1 and starting with the leftmost byte in 
the record. Using this convention makes it easier to 
remember key handles. Key handles can be 
determined at run time by using the IGETKD 
procedure to fetch key field descriptions. 


Note: If you are defining a nonkey field, this 
number is 0. 


‘oe Kdes(8) [high byte] = duplicates-allowed flag, 
descending flag, and case-insensitive flag 
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The duplicates-allowed flag = 1, the descending flag 
= 2, and the case-insensitive flag = 4. 


Add the values of the desired flags together and enter 
that number as the high byte. For example, to set the 
duplicates-allowed and case-insensitive flags, use: 


Kdes(8) = (256 * (1 + 4)) + field-mode ‘> 
duplicates-allowed flag 


A flag indicating whether duplicate values are 
allowed for this particular field. 


descending-flag 


A flag inverting the meaning of comparisons 
performed on this field. The result is that the 
records are inserted into the key set in 
descending instead of ascending order. It is 
most useful with split keys where the ordering of 
the different components might need to be 
inverted. 


case-insensitive-flag 


A flag causing string-based data types to ignore 
differences in case (for example, the values 
‘“‘FiRst”’ and “‘first’’? would be equal). 


Kdes(8) [low byte] = field-mode 


Tells if the field is a key. If it is a key, it tells if itis a 
split key. 


If the field is a nonkey field, field-mode=0O. If the field 
is a nonsplit key field, field-mode=1. If the field is a 
component of a split key, field-mode=2. 


Kdes(9) = filler 


A reserved word area. It must be initialized to zero. 
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The following example shows typical record and key 
descriptors: 


DIM RDES(3), KDES(9) 
"$INCLUDE: 'ISAM.INC' 


RDES(1) = 1 "1 Key field 
RDES(2) = 6 "Nonsegmented 
RDES(3) = 8 "Minimum record length 
FIELDNAME$="ID NUMBER" 

& KDES(1) = VARPTR(FIELDNAME$) ‘Field name pointer 
KDES(2) = 6 ‘Reserved-Set to zero 
KDES(3) = INTEGER "Data type—Integer 
KDES(4) = 1 "Segment 1 
KDES(5) = 1 "Position 1 
KDES(6) = 2 "Length of field in bytes 
KDES(7) = 1 "Key number is 1 
KDES(8) = (1*256) +1 "Duplicates allowed-—Nonsplit key 
KDES(9) 6 "Reserved-—Set to zero 

Examples 


The first example is the skeleton of a BASIC 
program—ISMSHELL.BAS on the ISAM 
diskette—that uses ISAM files. To use this, you 

\& would need to insert the appropriate values for the 
record and key descriptors and for the file and field 
names. 


Note the second COMMON statement in the 
program. When ISAM accesses your data file, it is 
essential that the fields of the data record are stored 
sequentially in memory. The COMMON statement 
provides an easy way to do this in BASIC. 


Also note that the following statement must appear at 
the beginning of each BASIC ISAM program. 


COMMON SHARED /ISAM/ IXSTAT, IOSTAT 


This allows you to access the ISAM status variables 


& in your program. 
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' FILENAME = EX1.BAS 


DEFINT A-Z 


DIM RDES(3) "Record Descriptor 
DIM KDES(9) "Key Descriptor 
COMMON SHARED /ISAM/ IXSTAT,IOSTAT "ISAM Status Variables 


COMMON /DATA.RECORD/ f1ld1,fld2,... 
$INCLUDE: '‘ISAM.INC' 


Below we set up the record descriptor 


RDES(1) = 1 "1 field declared 
RDES(2) = 6 "Not segmented 
RDES(3) = 6 ‘Default record allocation 


Below we set up the key descriptor 


FIELDNAME$ = " ; "Field name 

KDES(1) = VARPTR(FIELDNAME$) "Pointer to the field name 
KDES(2) = 6 "Reserved - Set to @ 

KDES(3) = ? "Data type - ? 

KDES(4) = ? "Segment # ? 

KDES(5) = ? "Position ? 

KDES(6) = ? "Length of field 

KDES(7) = ? "Key number is ? 

KDES(8) = (6 * 256) + 1 'Flags,Type of key 

KDES(9) = 6 "Reserved - Set to @ 

FN$ = " "Data file name 

PRECDESC! = VARPTR(RDES(1) ) "Pointer to the record descriptor 
PKEYDESC! = VARPTR(KDES(1) ) "Pointer to the key descriptor 
PDATDESC! = VARPTR(f1d1) "Pointer to the data descriptor 


Below we open the file in create mode 


CALL IOPEN(VARPTR(FN$), 3, PRECDESC!, PKEYDESC!, FILENUM) 
IF IXSTAT <> 6 THEN PRINT "OPEN FAILED": STOP 


In here you would put your BASIC program and 
the statements to create and use your ISAM file. 


CALL ICLOSE(FILENUM) 


END 


This example creates an ISAM file of records 
containing an ID number and a room number. It reads 
in the data from the keyboard, writes it to the file, and 
reads it back in to make sure that it was written out 
correctly. Note that we also define the field descriptor 
for ROOM, even though it is a nonkey field. 


" FILENAME = EX2.BAS 
"$LINESIZE: 132 


DEFINT A-Z 


DIM RDES(3) "Record Descriptor 
DIM KDES(18) "Key Descriptor 
COMMON SHARED /ISAM/ IXSTAT, IOSTAT "ISAM Status Variables 


COMMON /DATA.RECORD/ ID,ROOM 


Below we set up the record descriptor 


$TNCLUDE: 'ISAM.INC' 


RDES(1) = 2 '2 fields declared 

RDES(2) = 6 "Not segmented 

RDES(3) = 8 "Minimum Record Allocation 
FIELDNAME$ = "ID NUMBER" "Field Name 


Below we set up the key descriptor 


KDES(1) = VARPTR(FIELDNAME$ ) "Field name pointer - first key 
KDES(2) = 6 "Reserved - Set to 6 

KDES(3) = INTEGER "Data type - Integer 

KDES(4) = 1 "Segment 1 

KDES(5) = 1 "Position 1 

KDES(6) = 2 "Length of field - in this case implied 
KDES(7) = 1 "Key number is 1 

KDES(8) = (8 * 256) + 1 ‘Single, nonsplit key 

KDES(9) = 6 "Reserved - Set to 6 

ROOMNAME$ = "ROOM NUMBER" 

KDES(9+1) = VARPTR(ROOMNAME$ ) "Field name pointer 

KDES(9+2) = 6 "Reserved - Set to 6 

KDES(9+3) = INTEGER "Data type - Integer 

KDES(9+4) = 1 "Segment 1 

KDES(9+5) = 3 ‘Pesition 3 

KDES(9+6) = 2 "Length of field 

KDES(9+7) = 6 "Not a key 

KDES(9+8) = (6 * 256) + 6 'Nonkey field 


KDES(9+9) = @ "Reserved - Set to @ 


FN$ = "EX2.DAT" ‘Data file name 


PRECDESC! = VARPTR(RDES(1) ) "Pointer to the record descriptor 
PKEYDESC! = VARPTR(KDES(1) ) "Pointer to the key descriptor 
PDATDESC! = VARPTR(ID) "Pointer to the data descriptor 
KEYNUM = 1 

KEYLEN = 2 

RECSIZE = 4 "Length of data record 


Below we open the file in create mode 


CALL IOPEN(VARPTR(FN$), 3, PRECDESC!, PKEYDESC!, FILENUM) 
IF IXSTAT <> 6 THEN PRINT "OPEN FAILED": STOP 


INPUT "ENTER ID # (8 TO STOP) AND ROOM #";ID,ROOM 
WHILE ID <> 6 
VID = ID : VROOM = ROOM 
CALL IWRITE(FILENUM, PDATDESC! ,RECSIZE) 
IF IXSTAT = 13 THEN _ 
PRINT "DUPLICATE KEY - RECORD NOT WRITTEN":GOTO DONE 


Below we read the record back in to verify it 
CALL IREAD(FILENUM, PDATDESC!, RECSIZE) 
IF VID <> ID OR VROOM <> ROOM THEN _ 

PRINT "RECORD WAS NOT WRITTEN CORRECTLY" 
PRINT 
DONE : 

INPUT "ENTER ID # (8 TO STOP) AND ROOM #";ID,ROOM 
WEND 


CALL ICLOSE(FILENUM) 


END 
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This example shows how to use a string variable as a 
Key. 


' FILENAME = EX3.BAS 
"$LINESIZE: 132 


DEFINT A-Z 


DIM RDES(3) "Record Descriptor 
DIM KDES(9) "Key Descriptor 
COMMON SHARED /ISAM/ IXSTAT,IOSTAT ‘Isam Status Variables 


COMMON /DATA.RECORD/ ENAME$,ID$ 


"$INCLUDE: 'ISAM.INC' 


DEF FNSADD! (VARPOINTER) " get the address of a string 
given the varpointer of the string 
FNSADD! = PEEK(VARPOINTER + 3)*256.0 + PEEK(VARPOINTER + 2) 

END DEF 
OPEN "NUL" AS #9 LEN=27 ‘Open needed for FIELD 
FIELD 49, 58 

26 AS ENAME$, _ "Key field 

7_AS ID$ "ID field 


Below we set up the record descriptor 


RDES(1) = 1 "1 field declared 

RDES(2) = 6 "Not segmented 

RDES(3) = 6 "Default record allocation 
FIELDNAME$ = "EMPLOYEE NAME" "Field Name 


Below we set up the key descriptor 


KDES(1) = VARPTR(FIELDNAME$) "Field name pointer - first key 
KDES(2) = 6 "Reserved - Set to 6 

KDES(3) = STRING "Data type - String 

KDES(4) = 1 "Segment 1 

KDES(5) = 1 "Position 1 

KDES(6) = 26 "Length of field 

KDES(7) = 1 "Key number is 1 

KDES(8) = (6 * 256) + 1 "Single, nonsplit key 

KDES(9) = 6 "Reserved - Set to 6 


D-27 


D-28 


FN$ = "EX3.DAT" "Data file name 


PRECDESC! = VARPTR(RDES(1) ) "Pointer to the record descriptor 
PKEYDESC! = VARPTR(KDES(1) ) "Pointer to the key descriptor 
PDATDESC! = FNSADD! (VARPTR(ENAMES$) ) "Pointer to the data descriptor 
KEYNUM = 1 

KEYLEN = 26 

RECSIZE = 27 "Length of data record 


Below we open the file in create mode 
CALL IOPEN(VARPTR(FN$), 3, PRECDESC!, PKEYDESC!, FILENUM) 
IF IXSTAT <> 6 THEN PRINT "OPEN FAILED":STOP 


INPUT "ENTER EMPLOYEE NAME AND ID # (8 TO QUIT)";NAME$,I$ 
WHILE VAL(I$) <> 6 
LSET ENAME$ = NAME$ 
LSET ID$ = I$ 
CALL IWRITE(FILENUM, PDATDESC! , RECSIZE) 
IF IXSTAT = 13 THEN PRINT "RECORD NOT WRITTEN - DUPLICATE KEY" 
PRINT 
INPUT "ENTER EMPLOYEE NAME AND ID # (8 TO QUIT)";NAME$,I$ 
WEND 


CALL ICLOSE(FILENUM) 
IF IXSTAT <> 6 THEN PRINT "AFTER CLOSE, IXSTAT =";IXSTAT:GOTO DONE 


CALL IOPEN(VARPTR(FN$), 2, PRECDESC!, PKEYDESC!, FILENUM) 


IF IXSTAT <> 6 THEN PRINT "AFTER OPEN, IXSTAT =";IXSTAT:GOTO DONE 

PRINT 

INPUT "ENTER EMPLOYEE NAME FOR RECORD YOU WANT TO CHANGE’ ; _ 
NAME$ 


LSET ENAME$ = NAME$ 


CALL ISEEK(FILENUM, KEYNUM, PDATDESC!, KEYLEN, 2) ' GET EQUAL RECORD 
IF IXSTAT = 16 THEN PRINT ENAME$;"NOT IN THE FILE":GOTO DONE 

IF IXSTAT <> 6 THEN PRINT "SEEK FAILED - IXSTAT = ";IXSTAT:GOTO DONE 
PRINT 


INPUT "ENTER NEW EMPLOYEE NAME AND ID NUMBER";NAME$,I$ 
LSET ID$ = ZS 

LSET ENAME$ = NAME$ 

CALL IREWRITE(FILENUM, PDATDESC! , RECSIZE) 


IF IXSTAT <> 6 THEN PRINT "AFTER IREWRITE,IXSTAT = ";IXSTAT 
DONE: 

CALL ICLOSE(FILENUM) 

IF IXSTAT <> 6 THEN PRINT “AFTER CLOSE @2, IXSTAT =";IXSTAT 


CALL ICLOSE(FILENUM) 


END 


This program opens the file created with the previous 
example and prints out all the data records. 


Note that we don’t have to assign values to the record 
and key descriptors, because we are using a file that 
has already been created. 


' PILENAME = EX4.BAS 

'$LINESIZE: 132 

DEFINT A-Z 

COMMON SHARED /ISAM/ IXSTAT,IOSTAT 


Def FNsadd!(varpointer) 


end def 


Open "nul" as #9 Len=27 


Field #9, 

26 as ENAME$, _ 

7 as ID$ 

FN$ = "EX3.DAT" 
NULL! = 6 
PRECDESC! = VARPTR(NULL! ) 
PKEYDESC! = NULL! 
PDATDESC! = FNSADD! (VARPTR(ENAME$) ) 


KEYLEN = 28 


RECSIZE = 27 


"Isam Status Variables 


" get the address of a string 


" given the varpointer of the string 
FNsadd! = peek(varpointer + 3)*256.8 + peek(varpointer + 2) 


"Open needed for FIELD 


"Key field 
"ED field 


"Data file name 


"Pointer to the data descriptor 


"Length of data record 
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' Below we open the file in read/write mode 


CALL IOPEN(VARPTR(FN$), 2, PRECDESC!, PKEYDESC!, FILENUM) 


IF IXSTAT <> @ THEN PRINT "AFTER OPEN #3, IXSTAT =";IXSTAT:GOTO DONE 
PRINT:PRINT "THIS IS THE ENTIRE FILE :":PRINT 

CALL ISEEK(FILENUM, KEYNUM, PDATDESC!, KEYLEN, 8) ' GET EQUAL RECORD 
AGAIN: 

CALL IREAD (FILENUM,PDATDESC! , RECSIZE) 

IF IXSTAT <> 6 THEN PRINT "READ FAILED - IXSTAT =";IXSTAT 

PRINT ENAME$, ID$ 

CALL INEXT(FILENUM, KEYNUM) 

IF IXSTAT = @6 THEN GOTO AGAIN ‘' else the file is done 

DONE: 


CALL ICLOSE(FILENUM) 


END 


The following example shows how to use split keys. 
The program creates a file of 5 records consisting of 
an ID number, room number, and name. After 
creating the file, it reads it sequentially and prints out 
the records. 


Note: The order of the components in the split 
key is determined by the order in which they are 
declared, not by their order in the data record. 


" FILENAME = EX5.BAS 


“ST INESIZE = 132 


DEFINT A-Z 


DIM RDES(3) "Record Descriptor 
DIM KDES(18) "Key Descriptor 
COMMON SHARED /ISAM/ IXSTAT,IOSTAT "ISAM Status Variables 


COMMON /DATA.RECORD/ IID, IROOM, RNAME$ 
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"INCLUDE: 'ISAM.INC' 


Def FNsadd!(varpointer) get the address of a string 


given the varpointer of the string 


FNsadd! = peek(varpointer + 3)*256.6 + peek(varpointer + 2) 
end def 
OPEN "NUL" AS #9 LEN=32 " Needed for FIELD 
FIELD #9, 
6 AS ID$, _ 


6 AS ROOM$, _ 
26 AS NAME$ 


RDES(1) = 2 '2 fields declared 
RDES(2) = 6 ‘Not segmented 
RDES(3) = 32 "Minimum record allocation 


Below is the field description for the first 
component of the split key. 


FIELDNAME1$ = "EMP NAME" "Field Name 

KDES(1) = VARPTR( FIELDNAME 1$) "Field name pointer - first key 
KDES(2) = 6 "Reserved - Set to @ 

KDES(3) = STRING "Data type - String 

KDES(4) = 1 "Segment 1 

KDES(5) = 13 "Position 13 

KDES(6) = 26 "Length of field 

KDES(7) = 1 "Key number is 1 

KDES(3)s =~ CA" #256) +2 "Case Insensitive - Split key 
KDES(9) = 6 "Reserved - Set to 6 


Below is the field description for the second 


component of the split key. Note that the 
Key Number (KDES(9+7)) is the same for both 
components. 


FIELDNAME2$ = "EMP ID" "Field Name 


KDES(9+1) = VARPTR(FIELDNAME2$) "Field name pointer - first key 
KDES(9+2) = 6 "Reserved - Set to 6 

KDES(9+3) = STRING "Data type - String 

KDES(9+4) = 1 "Segment 1 

KDES(9+5) = 1 "Position 1 


KDES(9+6) = 6 
KDES(9+7) = 1 


"Length of field 
"Key number is 1 


KDES(9+8) = (6 * 256) + 2 ‘Split key 

KDES(9+9) = 6 "Reserved - Set to 6 

FN$ = "EX5.DAT" 

PRECDESC! = VARPTR(RDES(1) ) "Pointer to the record descriptor 


PKEYDESC! = VARPTR(KDES(1) ) 
PDATDESC! FNSADD! (VARPTR(ID$) ) 


"Pointer to the key descriptor 
"Pointer to the data descriptor 


i} 


KEYNUM = 1 
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Below is the key length. Note that it includes 
" the length of both components of the split key 

KEYLEN = 20 + 6 

RECSIZE = 32 "Length of data record 


CALL IOPEN(VARPTR(FN$), 3, PRECDESC!, PKEYDESC!, FILENUM) 
IF IXSTAT <> 6 THEN PRINT "INITIAL OPEN FAILED":GOTO FIN 


' 


FOR I=1 TO 5 
INPUT "ENTER ID#,ROOM# AND NAME"; IID, IROOM, RNAME$ 
LSET ID$ = MKI$(IID) 
LSET ROOM$ = MKI$(IROOM) 
LSET NAME$ = RNAME$ 
CALL IWRITE(FILENUM, PDATDESC! , RECSIZE) 
IF IXSTAT <> 6 THEN PRINT "WRITE FAILED" 
NEXT I 


CALL ICLOSE(FILENUM) 


CALL IOPEN(VARPTR(FN$), 8, PRECDESC!, PKEYDESC!, FILENUM) "REOPEN FOR READ-ONLY 
IF IXSTAT <> 6 THEN PRINT "REOPEN FAILED":GOTO FIN 


CALL ISEEK(FILENUM, KEYNUM, PDATDESC!, KEYLEN, 86) "SEEK TO FIRST RECORD 
IF IXSTAT <> 6 THEN PRINT "SEEK FAILED":GOTO FIN 


FOR I = 1 TO 5 
CALL IREAD(FILENUM, PDATDESC!, RECSIZE) 
IF IXSTAT <> 6 THEN PRINT "READ FAILED" 
PRINT CVI(ID$),CVI(ROOM$) ,NAME$ 
CALL INEXT(FILENUM, KEYNUM) 

NEXT I 


FIN: 
CALL ICLOSE(FILENUM) 


END 
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Note that normally, if one of the fields in the record is 

a string variable, you must put all of the fields of the 

record into a FIELD statement and declare them as 

strings (this is what was done in the previous 

example). This leads to wasted space, since, for 

example, you would need six characters to store an 
© integer—one character for each digit. 


However, if you use the MKI$ and CVI functions, you 
can store the integer as a 2-byte character string. This 
program uses this method to store ID numbers in a 
2-byte string. 


" FILENAME = EX6.BAS 


DEFINT A-Z 


DIM RDES(3) "Record Descriptor 
DIM KDES(18) "Key Descriptor 
COMMON SHARED /ISAM/ IXSTAT,IOSTAT "ISAM Status Variables 


"$INCLUDE: 'ISAM.INC' 


Def FNsadd!(varpointer) " get the address of a string 
" given the varpointer of the string 
FNsadd! = peek(varpointer + 3)*256.8 + peek(varpointer + 2) 
&Y end def 
OPEN "NUL" AS #9 LEN=17 " NEEDED FOR FIELD 
FIELD #49, 
TS:2AkS NAME$, _ 
2 AS ID$ 
RDES(1) = 2 "2 fields declared 
RDES(2) = 6 ‘Not segmented 
RDES(3) = 17 "Min. Record Allocation 
FIELDNAME = "EMP NAME" "Field Name 
KDES(i1) = VARPTR(FIELDNAME$ ) ‘Field name pointer - first key 
KDES(3) = STRING "Data type - String 
KDES(4) = 1 "Segment 1 
KDES(5) =.1 "Position 1 of record 1 
KDES(6) = 15 "Length of field 
KDES(7) = 1 "Key number is 1 
KDES(6) =--¢)-* -256:)) +22 "Duplicates - Split key 
KDES(9) = 6 "Reserved - Set to 6 
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FIELDNAM2$ = "ID NUM" ‘Field Name 


KDES(9+1) = VARPTR(FIELDNAM2$) "Field name pointer - second component 
KDES(9+3) = INTEGER "Data type - Integer 

KDES(9+4) = 1 "Segment 1 

KDES(9+5) = 16 "Position 16 of record 1 

KDES(9+6) = 2 "Length of field - in this case implied 
KDES(9+7) = 1 "Key number is 1 

KDES(9+8) = (6 * 256) + 2 "No duplicates - Split key 

KDES(9+9) = 6 "Reserved - Set to 6 

FN$ = "EMPFILE.DAT" "File name 

PRECDESC! = VARPTR(RDES(1) ) "Pointer to the record descriptor for open 
PKEYDESC! = VARPTR(KDES(1) ) "Pointer to the key descriptor for open 
PDATDESC! = FNSADD! (VARPTR(NAME$) ) "Pointer to the data descriptor 

KEYNUM = 1 

KEYLEN = 17 

RECSIZE = 17 "Length of data record 


CALL IOPEN(VARPTR(FN$), 3, PRECDESC!, PKEYDESC!, FILENUM) 
IF IXSTAT <> 6 THEN PRINT "INITIAL OPEN FAILED" 


CALL ISEEK(FILENUM, KEYNUM, PDATDESC!, KEYLEN, 8) ' GET FIRST RECORD 
INPUT "ENTER EMPLOYEE NAME AND ID NUMBER (6 TO STOP)";N$,IDNUM 


WHILE IDNUM <> 6 
LSET NAME$ = N$ 
LSET ID$ = MKI$(IDNUM) ' CONVERT THE INTEGER INTO 2 CHARS 
CALL IWRITE(FILENUM, PDATDESC! , RECSIZE) 
IF IXSTAT <> 6 THEN PRINT "WRITE FAILED" 
INPUT "ENTER EMPLOYEE NAME AND ID NUMBER (6 TO STOP)";N$,IDNUM 
WEND 


CALL ICLOSE(FILENUM) 


CALL IOPEN(VARPTR(FN$), 6, PRECDESC!, PKEYDESC!, FILENUM) " REOPEN FOR READ-ONLY 


IF IXSTAT <> 6 THEN PRINT "REOPEN FAILED" 
CALL ISEEK(FILENUM, KEYNUM, PDATDESC!, KEYLEN, 86) " SEEK TO FIRST RECORD 
IF IXSTAT <> 6 THEN PRINT "SEEK TO BEGIN FAILED":GOTO DONE 


WHILE IXSTAT = 6 
CALL IREAD(FILENUM, PDATDESC!, RECSIZE) 
IF IXSTAT <> 6 THEN PRINT "READ FAILED"+STR$(IXSTAT) 
PRINT NAME$,CVI(ID$) 
CALL INEXT (FILENUM,KEYNUM) 
WEND 


DONE: 
CALL ICLOSE(FILENUM) 


END 


D-34 


The following example creates, maintains, and outputs 
information from data bases. This data base system is 
used by the Zeck, French & Rowe Advertising Agency 
to manage its mailing lists. It contains names and 
addresses, as well as information on the income, sex, 
age, and housing situation of the people on the lists. 


‘oe Two keys are used for the data base files. Key 1 is the 
name field. Key 2 is a split key, containing three 
fields: zip code, sex, and income. The open.db and 
closedb routines call IOPEN and ICLOSE, 
respectively, to open and close the data base. 
Update.db uses ISEEK, INEXT, and IPREV to find 
records, and IREAD, IDELETE, and IWRITE to 
update records. Finally, print.db uses ISEEK to find 
particular records, and print the mailing labels. 


This example program is a realistic application using 
ISAM and the advanced features of BASIC. Note that 
much of this program is involved in the user interface; 
ISAM is powerful, but simple. 


The program solves the following problem: Zeck, 
&Y French and Rowe advertising agency maintains a large 

data base of names that they want to sell to various 

clients. The data base must: 

e Be easily maintained. 

e Generate mailing lists tailored to each client’s 
needs. (For example, give me all the people in 
Grand Island, NY over 30.) 


The program is organized into four sections: 


e The main menu. Select one of the three major 
functions. 


e Open the data base. Check for data base. Create 


& it if it does not exist. 
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e Update the data base. The available functions 
are: 


— Addanew record. 


— Delete or selectively update an existing 


record. > 


— Search for a record and move to the 
next/previous one. 


* Print out the data base. There are four selection 
criteria to limit the number of records printed. 


Demonstration Program 


'$Include: 'MAIL.H' "Record description of the ML prefixed names 
Dim keys(54), record(3) "Record and key descriptor arrays 
Dim names$(6) "Field names for creat 


ENTER$ = chr$(13) 


Function Definitions 


Def FNtoUpper$(s$) "Convert a string to upper case 


for. i= to lenGss) 
TS-—= mids(s$;,. 2. t) 
fESTE Ore 8 One es Se Chthen 
mid$(es4 452+) -— cars Case( T$) ~=.329 
next 2 


FNtoUpper$ = s$ 
end def 
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def FNcheck.open: 


-1 
Fncheck.open 


if filenum <> then _ 


ioe 


call mess("There is no open data base. 


"Check to make sure the data base is open 


Exit def 


Press SPACE to continue 


cali. get.key(-23;, 738, oa 
FnCheck.open = 6 
end def 
Def FNget.string$(lin, col, prompt$) 'Get an input at line & col putting a 
"print prompt on the status line 
call mess(prompt$) 
if col > 55 then nspace = 868 - col else nspace = 25 


locate lin, col: 
iocace. lin, cot 
Tine. input. —-; C$ 


FNget.string$ 


print string$(nspace, 


32) ‘clear out old value 


FNtoUpper$(cC$) 


end def 
Def FNupdate.string$(lin, col, oldval$) ‘Get an input at line & col 
"if there is no input return oldval 
lecate Lin, col 
line! input“ ".,.c$ 
le Gib exh Vera then _ 
FNupdate.string$ = oldval$ _ 


else 


FNupdate.string$ 


end def 


Def FNcheck.Comma$(s$) 


s$ 


a 


if instr ts$.. 6 then s$ 


FNcheck.Comma$ 


’ 


end def 


FNtoUpper$(c$) 


"Insure there is a comma in the string 
‘add one if there isn't one 


“ 


s$ 
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begin: "Start main line code 


filenum = -1 "Isam file is closed 


"Print out a little Banner 


mess1$ = "IBM Personal Computer -- BASCOM 2.6" 
mess2$ : ISAM Demonstration” 


cls 
for i=2 to 286 
locate 8, -4-1:) print *" 
locate 9, i-1: print 
next i 


mess1$; 
mess2$; 


" 


locate 7, 26: print string$(38, 265); 
locate 18, 26: print string$(38, 265) 


for i=1 to 866: x = sin(i): next i "Delay loop 
while.c$ <> ‘E" 


Redraw the main menu 


cls 

locate 1,26: print chr$(261)+string$(33, 265)+chr$(187); 

locate 2,26: print chr$(186)+" Zeck, French & Rowe “tenrs$ (13860 
locate 3,26: print chr$(186)+" Advertising Agency "+chr$(186); 


locate 4,26: print chr$(268)+string$(33, 265)+chr$(188); 


color. 1552 
locate 6,23: print "Direct Mailing Referral System" 
color 2,86 


locate 18, 25: print "Name of Data Base: "; 
color 15,2: print dbName$;: color 2, 6 


locate 12, 27: print Press O to Open Data Base"; 
locate 13, 27: print " Press U to Update Data Base"; 
locate 14, 27: print " Press P to Print Mailing Labels"; 
locate. 15, 27: print -" Press E ‘to Exit System’; 

locate 17, 25: print "Enter your selection '; 
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call get.key(17, 46, "OUPE") 


"Decide which function is requested 


If C$ = "O" then gosub open.db _ 

else If C$ = "U" then gosub update.db _ 

else If C$ = "P" then gosub print.db 
wend : End of main.loop 


gosub closedb 
end 


open.db: "Change the name of data base and try to open it 
"If the db doesn't exist then create a new one 


gosub closedb 


locate 23, 1: print string$(88, 32); "Clear line first 
locate 23, 1: Input "Name of new data base"; dbName$ 


call iopen(varptr(dbName$), 2, varptr(NULL), varptr(NULL), filenum) 
if ixstat = @ then return 


if ixstat <> 7 then gosub isamErr: return 


locate 24, 1: print "Creating the new data base ... ; 
"The data base doesn't exist so create the data base 

"Pirst create the key descriptors by reading them from data statements 
"For each of the 6 fields read in name string and then the 

‘read of the integer elements 


ror nkéys: = (i to. 6 


read names$(nkeys) "Read name into string 
keys((nkeys-1)*9 + 1) = varptr(names$(nkeys) ) 


for i=(nkeys-1)*9 + 2 to (nkeys-1)*9 + 9 
Read keys(i) 
next i 
next nkeys 
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Name, 6, data type, Segment, Position, Length, Key#, 
' Duplicate+Type, 6 
"Key 1 

Data: "Name 7; 47-5, .1,09;: 25, 1, 1284,° 8 

‘Split. Key- 2 
Data "Zip Poe lewd 2) 258° 6 
Dats.) Sen ek ost eel 2.1283, 8 
peace. (tncena’ | .8.° 7 3 63, &, 2, 258;8 

"Non keyed fields 
Date. “Ageress—.;-0...3,..1;.- 26, 36, 6,8; 8 
Beta (Age- 7.8 = As 4564, 25-8; 36, °8 


record(1) 6 

record(2) 6 

pRecDes! = varptr(record(1)) 
pKeyDes! = varptr(keys(1)) 


call iopen(varptr(dbname$), 3, pRecDes!, pKeyDes!, filenum) 
if ixstat <> 8 then gosub isamErr 


return 
closedb: "Close any open data base 
if filenum = -1 then return 


call iclose(filenum) 
if ixstat <> 6 then gosub isamErr 


filenum = -1 
return 


update.db: "ADD or delete records from the data base 


if not Fncheck.open then return 


cls 

locate 1, 26: print "Update the " dbName$ " data base "; 

locate 5, 7: print "Last Name: First Name:"; 
locate 6, 7: print "Address: Zip:"; 


locate 8, 386: print "Market Selectors"; 
locate 9, 1: print string$(88, 265); 


~ 


locate i3:, print "Sex Income"; 
locate 14, 7: print "Age"; 


locate 18, 5: print "Options are: Add, Delete or Update person." 
locate 19, 5: print "Search for, move to Next or Previous person."; 
locate 26, 5: print " Exit to main menu"; 

locate 22, 26: print "Enter Selection"; 
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call iseek(filenum, 1, NULL!, 6, 68) ‘Seek to the first record 
gosub read.record 


while(c$ <> "E") 


call get.key(22, 36, "ADUESNP") 
gosub redraw.form 


if c$ = "A" then gosub add.record _ 
else if c$ = "D" then gosub delet.record _ 
else if c$ = "U" then gosub update.record _ 
else if c$ = "S" then gosub search.record _ 
else if c$ = "N" then gosub next.record _ 
else if c$ = "P" then gosub previous.record 

wend 

eee 

return 

redraw.form: "Print out the current values in ML record 

locate 5, 26: print ML.Last.Name$; 

locate 5, 65: print ML.First.Name$; 

locate 6, 26: print ML.Address$; 

locate 6, 65: print using "#####"; cvs(ML.Zip$); 


locate 13, 26: print ML.Sex$; 

locate 13, 65: print using "###,###"; cvs(ML.Income$); 
locate 14, 26: print using "##"; cvi(ML.Age$) ; 

return 


delet.record: "Delete the current record 


call idelete(filenum) 
goto read.record 


update.record: "Modify the current values of a record 
lset ML.Last.Name$ = FNupdate.string$(5, 28, ML.Last.Name$) 
lset ML.First.Name$ = FNupdate.string$(5, 65, ML.First.Name$) 
lset ML.Address$ = FNcheck.Comma$(FNupdate.string$(6, 
26, ML.Address$) ) 
lset ML.Zip$ = Mks$( Val(FNupdate.string$(6, 
65, str$(cvs(Mi.Zip$s))} ))) 


| 


lset ML.Sex$ = FNupdate.string$(13, 28, ML.Sex$) 

lset ML.Age$ Mki$( Val(FNupdate.string$(14, 28, 
str$(cvi(ML.Age$)) )) ) 

lset ML.Income$ = Mks$( Val(FNupdate.string$(13, 65, 


str$(cvs(ML.Income$)) )) ) 
call irewrite(filenum, pRecord!, size.record) 
if not (ixstat = 8 or ixstat = 12) then gosub isamErr 


gosub redraw.form 
return 
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add.record: "Add a new record to the file 


lset ML.Last.Name$ = FNget.string$(5, 28, "Last Name") 

lset ML.First.Name$ = FNget.string$(5, 65, "First Name") 

lset ML.Address$ = FNcheck.Comma$(FNget.string$(6,28,"Address, City STATE") ) 
lset ML.Zip$ = Mks$( Val(FNget.string$(6, 65, "Zip")) ) 


lset ML.Sex$ = FNget.string$(13, 28, "Male Female") 
lset ML.Age$ = Mki$( Val(FNget.string$(14, 26, "Age")) ) 


lset ML.Income$ = Mks$( Val(FNget.string$(13, 65, "Income")) ) 


call iwrite(filenum, pRecord!, size.record) 
if not (ixstat = 6 or ixstat = 12) then gosub isamErr 


gosub redraw.form 
return 


search.record: "Search for a new record 


lset ML.Last.Name$ = FNget.string$(5, 28, "Last Name") 
lset ML.First.Name$ = FNget.string$(5, 65, "First Name’) 


call isavefp(filenum) 
call iseek(filenum, 1, pRecord!, 25, 2) 
if ixstat = 16 then _ 
call mess("Name not found"): call irestorefp(filenum): return 
goto read.record ‘Common code for next/previous 


next.record: "move the next record 


call inext(filenum, 1) 
goto read.record "Common code for next/previous 


previous.record: "move to the previous 


call iprev(filenum, 1) 


read.record: 
if ixstat = 11 then call mess("Beginning/End of Data file reached"): return 
if ixstat <> @ then gosub isamErr: return 


call iread(filenum, pRecord!, size.record) 
if ixstat <> #8 then gosub isamErr: return 


gosub redraw.form 
return 
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print .db: "Print out select records of the db 


if not Fncheck.open then return 
cks 
locate 1, 16: print "Print Mailing labels Market Selection"; 


locate 3, 5: print "Do you Want, eucput to Printer or File:"; 
carl gét.key(3,. 52; “PR 


" 


if cs bib 23 
if c§ 


then outName$ = "prn" 


"F" then locate 4, 17: Input "File Name: ", outName$ 


Il 


call mess("Press RETURN for all Zips") 


locate 6, 5: Input "Enter Lower Zip code: ",Select.Zip.Low! 
locate 6, 46: Input "Enter Upper Zip code: ",Select.Zip.High! 
if Select.Zip.High! = 6 then Select.Zip.High! = 99999 


call mess("Press RETURN for any Sex") 
locate 8, 5: print "Males, Females:"; 
call get.key(8, 38, "FM"+ENTER$) 


if c$ = ENTER$ then sex.list$ = "FM" else sex.list$ = c$ 


call mess("Press RETURN for all Incomes") 


locate 18, 5: Input "Minimum income: ",Select.Income.Low! 
locate 18, 4@: Input "Maximum income: ",Select.Income.High! 
if Select.Income.High! = 8 then Select.Income.High! = 999999 


call mess("Press RETURN for all Ages") 

locate 12, 5: Input "Minimum Age: ",Select.Age.Low 
locate 12, 4@: Input "Maximum Age: ",Select.Age.High 
if Select.Age.High = 6 then Select.Age.High = 999 


Open outName$ for Output as 1 
recount = 6: ixstat = 6 


"Set up the constant part of the search key 


search.key$ = string$(9, 6) ‘Create blank key 
mid$(search.key$, 6, 4) = Mks$(Select.Income.Low! ) 
Zip.Current$ = Mks$(Select.Zip.Low! - 1) 


lset ML.Zip$ Mks$(6) 


"For each zip code in the range 


while (ixstat = 6 and cvs(ML.Zip$) <= Select.Zip.High! ) 


"For each zip code in the range seek to the first set 
"Of records that fulf€ild “the search criteria 


mid$(search.key$, 1, 5) = Mks$(Cvs(Zip.Current$) + 1) + chr$(@) 
pSearch! = FNsadd!(varptr(search.key$) ) 


D-43 


call iseek(filenum, 2, pSearch!, 9, 4) 
if ixstat = 18 then goto print.end 


call iread(filenum, pRecord!, size.record) 
mid$(search.key$, 1, 4) = ML.Zip$ 
Zip.Current$ = ML.Zip$ 


for sex = 1 to len(sex.list$) 


select.sex$ = mid$(sex.list$, sex, 1) 
mid$(search.key$, 5, 1) = select.sex$ 


pSearch! = FNsadd!(varptr(search.key$) ) "Address of string 
call iseek(filenum, 2, pSearch!, 9, 4) 


if ixstat = 6 or ixstat = 12 then is 
call iread(filenum, pRecord!, size.record) 


if ixstat <> @ and ixstat <> 18 and ixstat <> 11 then a 
gosub isamErr: goto print.end 


"Read and print records while the zip is constant and the 
"values of the records fall within the high limits of the search 


while ixstat = 8 and mm 
ML.Zip$ Zip.Current$ and _ 
ML.Sex$ = Select.Sex$ and _ 
cvs(ML.Income$) <= Select.Income.High! 


"Since Age isn't a component in the split key we must examine 
"BOTH bounds of the selection criteria 


if cvi(ML.Age$) < Select.Age.Low or _ 
cvi(ML.Age$) > Select.Age.High then goto next.print 


print #1, left$(ML.First.Name$, instr(ML.First.Name$, " ")); 
print #1, ML.Last.Name$ 


"Extract the Address,City-State comma separated 
‘pair into two lines 


iComma = instr(ML.Address$, ",") 

print #1, left$(ML.Address$, iComma-1) 

print #1, mid$(ML.Address$, iComma+2) " " tab(25) cvs(ML.Zip$) 
print: #1, 

TEoOunt 7=—_reount = + «1 


next.print: 
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call inext(filenum, 2) 


if ixstat = 8 or ixstat = 12 then a 
call iread(filenum, pRecord!, size.record) 


if ixstat <> 68 and ixstat <> 11 then & 


gosub isamErr: goto print.end 


Wend 
next sex 


Wend 
print.end: 


close #1 
call mess(str$(rcount) _ 
+" Mailing labels printed. Press SPACE to continue..") 
Calicget.key(23, 78, "°*) 
return 


General purpose utility Functions 


isamErr: "Print out ISAM error message 


call mess("A serious ISAM Error has occurred"+str$(ixstat) 
+ Press SPACE to cont. J 


Call ‘get.key(23;, 78, " ") 
return 
"Subprogram to get.key a key from the user. The key is then converted 


"to upper case and checked to make sure its in a list of valid types 


sub get.key(x, y, valid.chars$) static 
shared c$, ENTER$ 


while (1) 
Locate sy :V;, 1 
cg = *’ 
while C$ = "": c$ = FNtoUpper$(inkey$): wend 


if instr(valid.chars$, c$) = 6 then es 


print. C$; : 
call mess(""): a "Clear out any old errors 
locate ,,8: “Purn cursor off 


exit sub 


if c$ = ENTER$ then cat 


c$ = "ENTER" "Transform enter character 
else 
print CS 
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call mess(C$+" is currently not a selection") 
wend 
end sub 
Subprogram to write out an error on the status line. 


sub mess(message$) static 


locate 24, 1: print space$(78); 
locate 24, 1: print message$; 


end sub 


Included File 


This is MAIL.H, the included file. The record layout 
is described in terms of the FIELD statement because 
it is the only record structuring facility in BASIC. 


: IBM BASCOM 2.8 ISAM Demonstration -- Include File 

Defint A-Z 

Common shared /ISAM/ Ixstat,Iostat ‘Isam status returned in this variables 
Def FNsadd!(varpointer! ) "Get the address of a string 


"given the varpointer of the string 


FNsadd! = peek(varpointer! + 3)*256.8 + peek(varpointer! + 2) 
end def 
size.record = 66 
Open "nul" as #9 Len=size.record ‘Open needed for FIELD 
Field #9, Pe 
15 as ML.Last.Name$, _ "Key 1 
16 as ML.First.Name$, ba “eey:*1 
36 as ML.Address$, 
4 as ML.Zip$, _ "1st component of split key 2 - type ML.Zip! 
1 as ML.Sex$, igs "2nd component of split key 2 
2 as ML.Age$, _ "type ML.Age% 
4 as ML.Income$ "3rd component of split key 2 - type ML.Income! 
pRecord! = FNsadd!(varptr(ML.Last.Name$) ) 
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This is the data dictionary for the file MAIL.DAT, 
translated into the REBUILD data-dictionary 
language. 


" Data Dictionary for file: MAIL.DAT -- Created by Version 2.66 of 
ISAM. 


Record Minimum Allocation is 8; 


Field "Name" IS 1 : 25 String Insensitive 
Keyed By 1 Duplicates Allowed ; 


Field "Address" IS 26 : 38 String ; 
Field "Age" IS 61 Integer ; 

Field "Zip" IS 56 Single MicroSoft ; 
Field "Sex" I8 66 : 1/S*tringe? 

Field "Income" IS 63 Single MicroSoft ; 


Split Keyset 2 is "Zip" "Sex" "Income" Duplicates Allowed ; 
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ISAM Subroutines 


This section describes the subroutines available in the 

ISAM Facility. These routines can be called from 

BASIC programs with the CALL statement. The 

interface to 8088 assembly language is also provided tS 
in this appendix, including an example of record and 

field descriptions, and a list of codes used in ISAM. 


ISAM is made up of 16 subroutines. The following 
sections describe each subroutine, list the syntax of 
the subroutine, and describe each parameter. If the 
subroutine returns a value (for example, IOPEN 
returns a file handle), the syntax section is followed by 
the word Returns: and the value that is returned. 
Where pointer values are indicated in the text, they 
should be obtained by using the VARPTR function to 
return a pointer to a variable of the proper size and 
data type. 
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we Purpose: 


Format: 


Remarks: 


ICLOSE 


ICLOSE closes the key and data files, and empties 
and frees any buffers for the named file. 


ICLOSE (fileno%) 


fileno % The file handle (integer value 
returned by IOPEN) identifying 
the file to be closed. 


While the ISAM file is open, portions of the key file 
are kept in memory. If the ISAM subroutine 
ICLOSE is not used to close the file, these sections 
of the key file may not be written to disk. When this 
happens, the file is marked damaged or “‘corrupted”’ 
(ixstat = 5), and IOPEN does not open the file. If 
this occurs, the REBUILD utility must be used to 
regenerate a good key file. 
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ICONTROL 


Purpose: 


Format: 


Remarks: 


Example: 
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ICONTROL writes all data held in memory to the “A 
data file. 


ICONTROL (request %, block!) 


request % Sets the type of [CONTROL 
request to Check point. 
Must have a value of 2. 


block! Pointer to the checkpoint 
parameters. 


The checkpoint function writes all data held in 
memory to the data file. It then closes and reopens 
the file used to hold the data. These two operations - 
guarantee that the data file is updated. The key file, 
however, is not updated; it is still held in memory 

and needs to be written to disk, by doing an 

ICLOSE. Should you not do an ICLOSE, 

REBUILD can restore the key file. 


The following program fragment establishes the 
arguments for the checkpoint function. 


CHECKPOINT.FILENUM% = 6 

CHECKPOINT.PFNAME! = 6 

PCHECKPOINTPARMS! = VARPTR(CHECKPOINT.FILENUMS) 

CALL IOPEN (VARPTR(FNAME$) ,3,PRECDESC! ,PKEYDESC! ,FILENUM) 


CHECKPOINT. FILENUM% = FILENUM 
CHECKPOINT.PFNAME! = VARPTR(FNAME$ ) 
CALL ICONTROL (2,PCHECKPOINTPARMS! ) 


& Purpose: 


Format: 


Remarks: 


IDELETE 


IDELETE deletes the current record and all key 
values associated with that record. 


IDELETE (fileno%) 


fileno % The file handle (integer returned 
by IOPEN) identifying the file 
from which the record is deleted. 


To delete a record from the file, seek to the record 
that you want to remove and call IDELETE. 


After the deletion the next record becomes the 
current record. If the record deleted was the last 
record in the file, an ixstat = 11 (keyset boundary 
reached) is returned after the deletion and currency 
is lost. 
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IDREAD 


Purpose: Reads a record from an ISAM file using a pointer to ‘eo 


the record. 


Format: IDREAD (fileno%, pbuffer!, length%, plocation!) 


Remarks: 


fileno% 


pbuf fer! 


length % 


plocation! 


Returns: 


length % 
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The file handle (integer returned 
by IOPEN) identifying the file to 
use. 


The pointer to the buffer to 
receive the record. 


The number of bytes that the 
record buffer (pbuffer!) can 
hold. For fixed length records ~ 
this is the record size. For 

variable length records it is the 
maximum size. An error returns 

(ixstat = 18) if the record was 

greater than /ength%. ISIZEOF 

can be used to determine the size 

of the current record. IDREAD 

uses length% to return the actual 

length of the record. 


A pointer to a 4-byte buffer that 
holds the pointer to the data. 
This number is set in IGETDP. 


The number of bytes read into “ 
the record buffer. 


IDREAD 


This data read routine is a special routine that reads 
directly from the file. Given a record pointer, this 
routine determines if the pointer points directly to a 
data record or to an indirection record. In either 
case, it returns the data record. Use IGETDP to get 
the data pointer. Other methods are not reliable if 
the file has been rewritten in memory but not yet 
written to disk. 
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IGETDP 


Purpose: 


Format: 


Remarks: 
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This routine fetches a pointer to a record. (The data “es 
pointer may not point directly at the record.) 


IGETDP (fileno%, plocation!) 


fileno % The file handle (integer returned 
by IOPEN) identifying the file to 
be used. 

plocation! A pointer to a 4-byte buffer that 


holds the pointer to the data. A 
single-precision number is big 
enough to be a data pointer. 


You can accumulate several data pointers and do the 
data reads later. 


It is a good idea to use IGETDP with IDREAD. 
IGETDP sometimes returns a pointer to an 
indirection record, but IDREAD compensates for 
this and reads the associated data record. All data 
pointers fetched by IGETDP are correct until the 
record is deleted or the file is reorganized by 
REBUILD. 


If you are using a file created by IBM Personal 
Computer SORT Version 1.00 and you modify that 
file by using either ISAM or REBUILD, remember 
that the pointers originally returned by SORT may 
not be valid. Use SORT again to generate new 


pointers. ~ 


IGETKD 


& Purpose: This routine returns key descriptions that were given 
when the file was created. 


Format: IGETKD (fileno%, keyno%, componetno%, pkeydes!) 
Remarks: 


fileno % The file handle (integer 
returned by IOPEN) 
identifying the file to be 
used. 


keyno % The key handle that 
identifies the key that you 
want information about. 


componetno % The desired key component 
& number. 


pkeydes! This is a pointer to a buffer 
to hold the key description. 
For a split key, this is a 
pointer to a 9-integer array 


that holds the key 
components. 
Returns: 
componetno % The number of fields in the key. 
For a nonsplit key, componetno % 
= 1. If componetno% = —-1, 


there was an error. 
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IGETKD 


Example: 
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Even if other fields were described when the file was 
created, they cannot be accessed through this 
routine. In addition, for split keys, IGETKD returns 
the number of components in the split key. 


If you want the field name returned, you must set 
Kdes(1) to point to a string of 40 bytes; otherwise, 
set Kdes(1) and Kdes(2) to zero. 


The key component number is a value from 1 to n, 
where n is the number of components of a split key. 
For keys that are not split keys, the key component 
number is 1. IGETKD uses componetno% to return 
the actual number of key components. If IGETKD 
returns —1 for the value of componetno%, there was 
an error. 


The following example returns the field name. 


field.name$=space$(4@) 
Kdes(1)=VARPTR(field.name$) 
PKDES!=VARPTR(Kdes(1) ) 

CALL IGETKD(FILENUM,KEYNUM,1,PKDES! ) 


v Purpose: 


Format: 


Remarks: 


INEXT 


For a given key, INEXT finds the record in the file 
with the next higher key value than the current 
record and makes that record the current record. 


INEXT (fileno%, keynum%) 


fileno % The file handle (integer returned 
by IOPEN) identifying what file 
to access. 

keynum % The key handle of the keyset that 


you are sequentially reading. 


If INEXT finds duplicate key values, it determines 
what the next record will be based on the order in 
which the records were entered. For records with 
identical key values, the next record is the younger 
record (the record entered later). If the key is 
declared as descending, the next record is the older 
record (the record entered earlier). 


If there are duplicate key values, ixstat = 12 is 
returned, for duplicate key warning. 
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IOPEN 


Purpose: IOPEN opens an ISAM file. ‘eo 


Format: IOPEN (VARPTR(filename$), mode%, precdes!, 
pkeydes!, fileno%) 


Remarks: 


VARPTR(filename$) 
A pointer to a character string 
that is the ISAM data file name. 
Data file names conventionally 
have the suffix ““.DAT”’. 
Filename$ must be less than 64 
characters long. 


mode % An integer specifying the mode 
in which to open the file. The “ 
four modes are: 


0: Read Only Data file can 
only be read. 


1: Write Only New data file 
is created 
and can only 
be written to. 


2: Update Data file can 
be written to 
and read. 


3: Read/Write New data file 
is created 
and can be “ 
written to 
and read. 
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IOPEN 


precdes! Single-precision number pointing 
to start of record description. 
The record description contains 3 
integers: the number of field 
descriptions, the record type 
(segmented or nonsegmented), 
and the minimum data record 


allocation. 

pkeydes! Single-precision number pointing 
to the start of the key 
description. 

Returns: 

fileno % An integer returned by ISAM to 
identify the file given in 
filename§$. 

YY IOPEN returns a handle to be used to identify the 


file in other ISAM operations. When creating a new 
file (mode% = 1 or 3), you must include a record 
description. The record description must at least 
contain descriptions for all key fields, and may 
contain descriptions for nonkey fields. The record 
description is not necessary when you are reading or 
updating a file (mode% = 0 or 2). 
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IPREV 


Purpose: 


Format: 


Remarks: 
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For a given key, IPREV finds the record in the file 
with the next lower key value than the current 
record, and makes that record the current record. 


IPREV (fileno%, keynum%) 


fileno % The file handle (integer returned 
by IOPEN) identifying what file 
to access. 

keynum % The key handle. 


If IPREV finds duplicate key values, it determines 
what the next record will be based on the order in 
which the records were entered. For records with 
identical key values, the “‘previous”’ record is the 
older record (the record entered earlier). If the key 
is declared as descending, the previous record is the 
younger record (the record entered later). 


If there are duplicate key values, ixstat = 12 is 
returned, for duplicate key warning. 


& Purpose: 


Format: 


Remarks: 


IREAD 


IREAD reads the current record into the buffer. 
This routine does not change the file position. 


IREAD (fileno%, pbuffer!, length %) 


fileno % 


pbuf fer! 


length % 


Returns: 


length % 


The file handle (integer returned 
by IOPEN) identifying the file in 
which to read. 


Pointer to buffer to receive the 
current record. 


The number of bytes that the 
record buffer (pbuffer!) can 
hold. 


The number of bytes read into 
the record buffer. 


For fixed length records, /ength% is the record size. 
For variable length records, it is the maximum size. 
An error returns (ixstat = 18) if the record was 
greater than /ength%. ISIZEOF can be used to 
determine the size of any record. IREAD uses 
length% to return the actual length of the record. 
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IRESTOREFP 


Purpose: IRESTOREFP restores the file position and the key ‘o 
of reference that was saved by the last ISAVEFP 
call. 


Format: IRESTOREFP (fileno %) 
Remarks: 


fileno% The file handle (integer returned 
by IOPEN) identifying what file 
to access. 


IRESTOREFP can be used to return quickly to a 
position in a file that was previously marked with 
ISAVEFP. 
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‘oe Purpose: 


Format: 


Remarks: 


IREWRITE 


This subroutine rewrites an ISAM record and 
updates the appropriate Keys. 


IREWRITE (fileno%, pbuffer!, length %) 


fileno% The file handle (integer returned 
by IOPEN) identifying the file in 
which to rewrite. 


pbhuffer! Pointer to the buffer that holds 
the record to be rewritten. 


length % The number of bytes to be 
written (the length of pbuffer/). 


Use the VARPTR function to get pbuffer!. 
Length% must be greater than or equal to the 
minimum record allocation. The minimum record 
allocation is set in RDES(3); the default is 8 bytes. 
IREWRITE deletes the current record and the 


appropriate key values. It then writes out the new 
record, which becomes the new current record. 
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ISAVEFP 


Purpose: ISAVEFP saves the current file position. ‘ty 
Format: ISAVEFP (fileno %) 
Remarks: 


fileno % The file handle (integer returned 
by IOPEN) identifying what file 
to access. 


The saved file position can then be restored by 
IRESTOREFP. Use ISAVEFP to place a ‘“‘book 
mark” in your file and use IRESTOREFP to find it. 
This is faster than using ISEEK to find your place 
again because ISAVEFP saves the most recent key 
of reference established by ISEEK. 
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Remarks: 


ISEEK 


ISEEK searches the file for a specified key, and, 
optionally, a specified value of that key. 


ISEEK (fileno%, keynum%, pkey!, keylen%, 


mode %) 


fileno % 


keynum % 


pkey! 


keylen % 


mode % 


The file handle (integer returned 
by IOPEN) identifying the file in 
which to seek. 


The key handle. This value can 
be found by IGETKD. 


This is a pointer to a buffer 
containing the key value to 
search for. 


Integer length of the key value in 
bytes. 


Integer indicating what to search 
for. The search modes are: 


0 First record with 
specified key. 


I Last record with 
specified key. 
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ISEEK 


2 Key equal to this 
value. This positions 
the file to the first ‘y 
record matching the 
key value in both value 
and length. 


3 Key greater than this 
value. This positions 
the file to the first 
record with a key 
value greater than the 
specified key value. 


f Key greater than or 
equal to this value. 
This positions the file 
to the first record with 
a key value equal to or 
greater than the 
specified key value. 


2 First equal key, seek 
on short length. 
Returns key found 
only if there is a 
subkey (key of shorter 
length) that is equal to 
the searched value. 


ISEEK can locate the first or last record, or the first 
record with a value equal to or a value greater than 
the specified key value. 


ISEEK 


ISEEK determines what record is the ‘“‘first’’ or 
‘last’? record based upon the value of the specified 
key field in that record. Records are arranged 
alphabetically and numerically (numbers come | 
before letters). When there is more than one record 
with the same value in the specified key field, order 
is determined by the order in which the records were 
originally entered, with older entries coming before 
younger entries. If a key is declared as descending, 
the opposite is true; younger entries come before 
older entries. 
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ISIZEOF 


Purpose: 
Format: 


Remarks: 
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Returns the number of bytes in the current record. 


ISIZEOF (fileno %, fillsize %) ry 
fileno % The file handle (integer returned 
by IOPEN) identifying what file 
to access. 
Returns: 
fillsize % Integer size of current record. 


This can be useful when an ISAM file is opened for 
reading and was created by another program or when 
the record has variable-length fields. 


Purpose: 


oe Format: 


Remarks: 


IWRITE 


IWRITE writes a new record to the ISAM file. 


IWRITE (fileno%, pbuffer!, length%) 


fileno % The file handle (integer returned 
by IOPEN) identifying the file in 
which to write. 


pbhuffer! Pointer to buffer that holds the 
record. 
length % The number of bytes to be 


written (the length of pbuffer!). 


Length% must be greater than or equal to the 
minimum record allocation. The minimum record 
allocation is set in RDES(3); the default is 8 bytes. 


IWRITE automatically searches the data file for the 
first place large enough to write the record. It also 
automatically puts the appropriate key information in 
the Key file. 


The newly written record becomes the current 
record. 


If you attempt to write a record with a duplicate key 
and duplicates are allowed, the record is written and 
ixstat returns a value of 12. If duplicates are not 
allowed, the record is not written and an ixstat of 13 
is returned. 


ISAM Codes 


Status Indicators 
These values are returned by ISAM into ixstat. a 


0 Successful completion — no error 


1 Invalid ISAM file number 


2 Invalid key descriptor 
3 Invalid key number 
4 File and ISAM version mismatch 


You may be using a COBOL version 1.00 
ISAM file. Change it to a BASIC 
Compiler 2.00 file by using the REBUILD 
utility. See “ISAM REBUILD Utility.” 


5 File damaged 
You are trying to use a file that was not 
ICLOSED. Use REBUILD to repair the 
file. 


6 Memory full 


7 File or directory not found, or invalid name 
8 Permission to access the file denied 
9 Disk is full or file is too large 


10 Key not found 


The key value you looked for using ISEEK % 
was not in the file. 
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11 Keyset boundary reached (start or end) 
You are at the beginning or end of a file. 
12 Duplicate key warning 


See the INEXT subroutine under “ISAM 
Subroutines”’ for details. 


| Be Duplicate key error 
14 Record locked 


15 File locked 


16 Unrecoverable error: Disk I/O operation 
failure 

1} File position (location of current record) has 
been lost 


18 Buffer overflow (buffer too small) 


& 19 Data dictionary error 
Use the REBUILD utility to correct the 
error. 
20 Invalid segment number in field descriptor 


21 Invalid field type in field descriptor 
ae Reserved value in field descriptor nonzero 
Zo Key Length out of range in field descriptor 
It must be 250 bytes or less. 
24 Multiuser failure 
w “ao Beginning of keyset boundary reached 


26 Critical DOS error has aborted ISAM 
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zi ISAM has not been loaded into memory 


28 Invalid mode given in IOPEN (valid modes are 


0-3). 

Open Mode Definitions a) 

0 Read only 

1 Clear file, and open for write only 

2 Read and write 

3 Clear file, and open for read and write. 
Seek Modes 

0 First key in Key set 

1 Last key in key set 

- Key equal to this value 

3 Key greater than this value 

4 Key greater than or equal to this value 
5 First equal key, seek on short length. 
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ICONTROL Requests 


w) Checkpoint function 
Data Types 
IK INTEGER 1 Signed integer \— 2 


(BASIC’s % type) 


IK STRING 5 Character string 
(BASIC’s $ type) 


IK NUMERIC 6 Free format, integer/real 
ASCII number 
IK _SMICRO 7 Single-precision, real 


number \-— 4 
(BASIC’s ! type) 


IK _DMICRO 10 Double-precision, real 
number \-— 8 
(BASIC’s # type) 


we The above data types that are followed by a backslash 
and a number have the given fixed size in bytes. This 
value must always be given when referring to these 


types. 
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ISAM Assembly Language Interface 


This section is a reference on the DOS assembly 

language interface to ISAM. The BASIC interface to 

ISAM is built on top of the assembly language 

interface to the same routines. These routines are “ 
based on the 8088/6 interrupt instruction. BASIC 

programs translate the BASIC calling convention into 

a DOS compatible call. For the great majority of 

applications you should never have to use the 

assembly language interface. 


There are 16 entry points into ISAM. There is one 
function code for ISAM: AH=92H. Therefore, AL 
contains the ISAM subfunction, or exact entry point 
desired. ISAM takes one to five parameters that are 
passed to ISAM in a parameter block that is pointed to 
by DS:DX. All the pointer parameters are relative to 
the current DS segment. In general: 


CALL 
CX Ce eee DS:DX = ISAM PARM BLOCK 


OX 
225 ae 
ay i os Se 
= 
a Oe Pa 
os 
= as ale 
= Se Ss a 
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After an ISAM call the registers are as follows. ISAM 
returns two types of values in AX and DX. DX 
always contains the status code of the operation. A 
zero means that the operation was successful. The 
return value is different for each ISAM call. For 
example, IREAD returns the size of the record read. 


| RETURN | CODE | 
| CU 
_ 
i ie 
i. | ae 
ke 


CALL 
AX = ISAM STATUS CODE 


IF carry set 
ISAM error 


A typical set of data structures and instructions to call 
ISAM would look like this: 


MOV DX,OFFSET ISAM_Open 


MOV AH,92H ;ISAM function request number 
MOV AL,@ ;ISAM subfunction for IOPEN 
INT Zi 

JNC okl ;Check for error 
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Structure of ISAM Subroutines 
ICLOSE (AL = 1) 
ISAM __ file STRUC 
file handle DW ? ;File handle to use “ 


ISAM_ file ENDS 


ICONTROL (AL = 15) 


Before you use ISAM, you must initialize ISAM by 
making an ICONTROL call with a function equal to 4. 
For this function, pl must be equal to 0. 


To see if ISAM has been installed, use function=S. 
All parameters are ignored. If ISAM is resident in 
memory, AX is set to zero. 


ISAM _ control STRUC 


Function DW ? ‘Function number 
: of request 
pcParms DD OFFSET cParms_ ;Pointer to 

; parameters 


ISAM __ control ENDS 
ISAM _cParms STRUC 


pl DW .? ;control parm 1 
pe TY 2 ;control parm 2 


ISAM__cParms ENDS 
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IDELETE (AL = 12) 
ISAM __ file STRUC 


file handle DW ? ;File handle to use 


& ISAM _ file ENDS 


IDREAD (AL = 10) 

ISAM _ dread STRUC 
file handle DW? ;File handle to use 
pbuffer DD ? ;pointer to record buffer 
buffer__size DW? ;size of record buffer 


plocation DD ? ;Pointer to 4 byte integer 


ISAM __ dread ENDS 


IGETDP (AL = 11) 


w ISAM _ getdp STRUC 
file handle DW ? ‘File handle 
: to use 
plocation DD OFFSET location ;Pointer long 
: integer 


ISAM __ getdp ENDS 


location DD ?_ ;Long integer low/high 
: word order 
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IGETKD (AL = 14) 


ISAM___ getkd STRUC 


file handle DW ? ;File handle to use 
key# DW ? ;Key number 

: to move on 
subkey# DW ? split key# 


pKey des DD OFFSET Key_ des ;Pointer 
; to key descriptions 


ISAM__getkd ENDS 
The field pName in Key__des is a pointer to a data 


area to store the field name. If you set this field to a 
nonzero value, any field name is deposited there. 


INEXT (AL = 3) 
ISAM _ prev__next STRUC 


file handle DW ? _ ;File handle to use 
key# DW ? _ ;Key number to move on 


ISAM __prev__next ENDS 


IOPEN (AL = 0) 

Returns the ISAM file handle in AX. The file handle is 
used in the rest of the ISAM calls to specify which file 
you are working with. The parameter block is: 


ISAM __ open STRUC 


pFname DD ? ;File name 
mode DW? ;Mode to open 
file 


eS DD OFFSET Record ;Pointer to 
record description 


pKey DD OFFSET Key ;Pointer to field 
descriptors 


ISAM __ open ENDS 
The structures for record and key descriptions are: 
ISAM __ record STRUC 

n__ field des DW ? ;Number of field 


YY descriptors 
eee DB ? ;Segmented record flag 
reserved DB 0 


ISAM __ record ENDS 
ISAM _ field des STRUC 
pName DD O ;Pointer field name 


data__type DB ? ;Data type of field 
sub type DB O ;Always 0 


segment DW ? ;Segment number of field 
offset DW ? ;Offset of field, starting at 1 
length DW ? ;Length of field 


key num DW? ;Key number of field 
key type DB ? ;Type of key 

Y flags DB ? ;Various bit flags 
reserved DW 0O 


ISAM _ field _des ENDS 


D-79 


IPREV (AL = 4) 
ISAM _ prev__next STRUC 


file handle DW ? ;File handle to use 
key# DW ? ;Key number to move on 


ISAM __prev__next ENDS ‘y 


IREAD (AL = 7) 

ISAM _ read_ write STRUC 
file handle DW ? ;File handle to use 
pbuffer DD ? ;pointer to record buffer 


buffer__size DW ? ;size of record buffer 


ISAM __read__write ENDS 


IRESTOREFP (AL = 6) 


ISAM _ file STRUC 


file handle DW ? ;File handle to use 


ISAM __ file ENDS 


IREWRITE (AL = 9) 

ISAM __ read__write STRUC 
file handle DW ? ;File handle to use 
pbuffer DD ? ;pointer to record buffer 


buffer size DW ? ;size of record buffer 


ISAM _ read___write ENDS ) 
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ISAVEFP (AL = 5) 
ISAM _ file STRUC 
file handle DW ? ;File handle to use 


ISAM __ file ENDS 


ISEEK (AL = 2) 


ISAM _ seek STRUC 


file handle DW ? ;File handle to use 

key# DW ? ;Number of Key to seek on 
pkey DD ? ;Pointer to key to seek to 
key size DW ? ;Size of key 

mode DW ? ;Type of seek 


ISAM __ seek ENDS 


& ISIZEOF (AL = 13) 
ISAM _ file STRUC 
file handle DW ? ;File handle to use 


ISAM ___ file ENDS 


IWRITE (AL = 8) 
ISAM _read_ write STRUC 


file handle DW ? ;File handle to use 


pbuffer DD ? ;pointer to record buffer 
buffer__size DW ? ;size of record buffer 
we ISAM __read__write ENDS 
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ISAM REBUILD Utility 


The REBUILD Utility version 2.00 is a tool for 
creating key files and changing data dictionaries. 
REBUILD can be used on indexed files created by 
either multi-key ISAM (BASCOM version 2.00) or 
single-key ISAM (COBOL version 1.00). 


You can also use REBUILD to repair your Key files if 
you ever damage them. You can damage your key file 
by erasing all or part of it, or by failing to use ICLOSE 
to close an ISAM file. Key files can also be damaged 
if your system goes down while an ISAM file is open. 
If this happens, any attempt to access the file returns 
ixstat = 5. If you know or suspect that your key file 
has been damaged, you can use REBUILD to repair 
the file. REBUILD erases the old key file and builds a 
new key file by using the information in your data file. 


You can also use REBUILD to change or add keys for 
a particular file. Suppose, for example, you have a file 
EMPLOYEE.DAT whose only key is the employee 
name. You can use REBUILD to change the Key to 
the social security number. 


REBUILD only changes the indexing information, not 
the actual data in the data file. You have to make sure 
that the descriptions that you give REBUILD 
accurately describe the format and content of your 
data file. If you use REBUILD to change the name 
field to an integer data type, for example, REBUILD 
trusts you to make sure that the name field contains 
integers. It does not check or change any of the data. 


REBUILD is also useful if you have an ISAM file that 
has been extensively updated. The more an ISAM file 
has been rewritten, the more likely it is that there is 
wasted space inside the file. 
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This is only likely if you are using variable length 
records because rewriting can generate indirection 
records. Whenever you tell REBUILD to copy a file, 
it compresses the input data file by removing free 
space and indirection records. 


~ Using the REBUILD Command 


You can start REBUILD from the command line. The 
syntax for providing arguments on the command line 
is: 


REBUILD [source file],[target file],{ key des],[{dd-file] 
[ / switches][;] 


Note that the comma (,) delimiter is not optional. If 
you do not want to specify a particular argument, use 
the comma to indicate which argument is not desired. 
If, for example, you do not want to specify a key 
description enter: 


REBUILD source,target,,dd-file; 


The semicolon (;) can be used to specify that no 
remaining arguments are desired. For example, if you 
are only specifying source and target you can enter: 
REBUILD source,target; 


REBUILD prompts you for any arguments it needs 
that are not provided. 


The command line arguments supported by REBUILD 
2.00 are: 


source The name of the data file. 
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target 


key-des 


The name of the output file. If this 
argument is present, source is copied into 
target, all free space is removed from target, 
and the key file generated is named 
target.key. 


The target argument is usually left out of the 
command line to avoid unnecessarily 
copying the data file. You must specify 
target if you want to compress your data 
file. You must also specify target if keys are 
being added or modified, or if you are 
changing the data dictionary in any way. 
You can give REBUILD the new data 
dictionary information from the dd-file 
argument or from key-des. 


Description of a single-key. The key-des 
parameter can be used only when the rebuilt 
file contains only one key. 


The format for a key description given from 
the command line is: 


position:size data-type 
The parameters used here are: 


position The key field location (starting 
position in the data record). 


size The Key field length. 


data-type The data type of the key field. 
This type must be specified. 


Note: Earlier versions of 
REBUILD assumed a 
default data type of 
alphanumeric. , REBUILD 
2.00 assumes no data 
type, therefore, the type 
must be supplied. 


dd-file The dd-file contains a description of the 
data dictionary using the REBUILD 
data-dictionary language, as described in 
the section ““The REBUILD 
Data-Dictionary Language.”’ 


If the command line contains target and 
dd-file, REBUILD uses dd-file to create a 
new key file and a new data dictionary for 
target. However, if dd-file is specified 
without target, REBUILD ignores dd-file 
and uses the data dictionary from source to 
build the new key file. 


switches Four switches can be used on the command 
line. When entering more than one switch, 
be sure to enter a slash (/) before each 
letter. The following sections explain each 
switch. 


Printing the Data Dictionary - /p 


The ‘“‘Print”’ switch, /p, prints a description of the data 
dictionary to the screen. The output can be redirected 
to a file or device. For example, to write the 
description of the data dictionary from source into the 
file any-file enter: 


REBUILD source/p ; > any-file 
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If you want to change a key in a file, use the /p switch 
to remove the data dictionary and an editor to edit the 
file. You can then use REBUILD again with the new 
data dictionary as dd-file. See ““Changing Key 
Information” later in this section for more details. 


Eliminating Queries From REBUILD - /f 


The ‘“‘Force”’ switch, /f, allows REBUILD to perform 
other routines without waiting for your response. For 
example, if you specify a target file that already exists, 
REBUILD usually prints on the screen: 


Target file already exists target 
Enter ’y’ to delete => 


The /f switch suppresses this query, and REBUILD 
automatically deletes the existing target file. 


Reducing Output to the Screen - /t 


The ‘‘Terse’”’ switch, /t, sets REBUILD in the terse 
mode; REBUILD does not print as much information 
on the screen. For example, you copy a file without 
using the /t switch, REBUILD prints a description of 
the data dictionary (in the REBUILD data-dictionary 
language) on the screen. If you specify the /t switch, 
the description is not printed. 


Removing the Data Dictionary - /s 
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The ‘“‘Single-key”’ switch, /s, tells REBUILD to copy 
source into target, removing the data dictionary and 
free space. No key file is built. This is used to create 
a data file that is compatible with the single-key 
REBUILD Utility, version 1.10. 


Generating a New Key File 


REBUILD can usually create a new key file to replace 

damaged key files. Anytime you enter a REBUILD 

command (unless you use the /s switch), REBUILD 
& attempts to create a new key file. 


There are at least four ways to damage a Key file: 


1. Erase all or part of the Key file. 


2. Fail to use ICLOSE to close an ISAM file that 
has been opened by IOPEN for update. 


3. Lose power to the system, or reboot the operating 
system while an ISAM file is open. 


4. Run out of disk space while writing to an ISAM 
file. 


Let’s assume that the ISAM file EMPLOYEE.DAT 
was open when a power failure occurred. ISAM often 

& keeps indexing information in memory while a file is 
open and, unless ICLOSE is used to close the file, that 
information is not written back to the key file. 
Therefore, EMPLOYEE.KEY is incomplete and 
ISAM marks it as a “corrupted” file. IOPEN does not 
allow you to open a corrupt file. To use the 
information in the file EMPLOYEE.DAT, you have to 
build a new Key file. 


To build a new key file enter: 


REBUILD EMPLOYEE.DAT; 


After erasing the existing EMPLOYEE.KEY file, 
REBUILD reads the data dictionary to get the key 
description(s) in EMPLOYEE.DAT, and each record 

YY in EMPLOYEE.DAT, and build new indexes for the 
data in EMPLOYEE.DAT. These indexes are written 
into a new file named EMPLOYEE.KEY. 
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If your data file was created by IBM PC SORT or by 
IBM PC COBOL it does not contain a data dictionary. 
If there is no data dictionary, you have to give 
REBUILD record and key descriptions on the 
command line or in dd-file. 


There are two cases in which REBUILD may not be 
able to completely recover a damaged Key file. 


1. If an indexed file is open when electrical power to 
the computer system is interrupted, or when the 
operating system is rebooted, that file can be 
damaged in ways that REBUILD cannot fix. 


If the system failure occurs during a file update 
job, the file may contain records with both 
original and new information. REBUILD cannot 
determine what part of the data was written 
during the terminated job and, therefore, cannot 
exclude the new, incomplete data from the rebuilt 
file. 


Note: Adding a “‘current date”’ field to data 
records sometimes helps discriminate 
between old and new data. 


If the system failure occurs while records are 
being added to the indexed file, the last 512 bytes 
of data may not be written to disk. REBUILD 
detects that information is missing from the end 
of the file but cannot add it to the recovered file. 


2. A data file can also be damaged if you run out of 
disk space during IWRITE. 


You know that space was exhausted during the 
IWRITE operation when IWRITE produces an 
error (ixstat = 9) indicating that the disk is full. 
When this happens, call ICLOSE to write as “ 
much information as possible to disk. 
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It is likely, however, that ICLOSE also returns an 
error indicating that disk space is full. If it does, 
the last 512 bytes of information are not in the 
data file. Those 512 bytes cannot be recovered 
by REBUILD. 


Note: If your ISAM file is damaged, you may get 
an error message Data dictionary in data file is 
damaged. If this occurs, you must use REBUILD 
with the /p switch to put the data dictionary into 
ASCII format. You can then use an editor to 
correct any errors in the data dictionary and 
REBUILD—with dd-file as an input 
parameter—to remake the data file. 


Compressing a Data File 


Now, let’s assume that your data file, 
EMPLOYEE.DAT, has been updated extensively. It 
may contain unusable space in the form of free 

& records and, if the file contains variable-length 
records, indirection records. 


Whenever you specify target on the command line, 
REBUILD produces a compressed data file in addition 
to a Key file. To produce a compressed version of 
EMPLOYEE.DAT enter: 


REBUILD EMPLOYEE.DAT ,COMPRESS.DAT; 


REBUILD reads the information in 
EMPLOYEE.DAT and copies the data dictionary and 
data, first removing any unusable space, to the new 
file COMPRESS.DAT. Then, REBUILD builds a key 
file. COMPRESS.KEY, that contains indexing 
information for the data in COMPRESS.DAT. 


Changing Key Information 


If you want to add or delete a key from an ISAM file, 
or change the description of an existing field, you have 
to change both the data dictionary and the key file. 
You can either do this by creating a new ISAM file, 
with the new key information, or by modifying the 
existing data file and key file. To modify the data file 
and key file use REBUILD. 


Let’s use the example mentioned at the beginning of 
the appendix. Your ISAM file, EMPLOYEE.DAT, 
contains employees’ names, addresses, social security 
numbers, and dates of employment. When you 
opened the file, you defined the field containing 
employees’ names as a key field. Now, you would like 
to define the date-of-employment field as a key field 
as well. 


First, put a copy of the data dictionary from 
EMPLOYEE.DAT into a form you can modify. Using 
the /p switch in the REBUILD command prints a 
copy of the data dictionary from source to your screen. 
To redirect this output to a separate file enter: 


REBUILD EMPLOYEE.DAT/P ;> EMPLOYEE.DD 


The file EMPLOYEE.DD now contains the data 
dictionary from EMPLOYEE.DAT—+ranslated from 
binary into the REBUILD data-dictionary language. 
The following section describes this language in detail. 
The second step is to edit the file EMPLOYEE.DD, 
adding a statement that defines the 
date-of-employment field as a key field. Finally, after 
the file EMPLOYEE.DD has been modified, enter: 


REBUILD EMPLOYEE.DAT,NEW.DAT, ,EMPLOYEE.DD 


This command instructs REBUILD to: 


1. Copy the records from EMPLOYEE.DAT to 
NEW.DAT, removing any free space or 
indirection records. 


2. Translate the information from EMPLOYEE.DD 
into binary and add this new data dictionary to 
NEW.DAT. 


3. Use the new data dictionary in NEW.DAT, and 
the records copied from EMPLOYEE.DAT, to 
build a new key file NEW.KEY. 


Using COBOL 1.00 ISAM Files 


The key formats of ISAM files produced by COBOL 
1.00 and BASIC Compiler 2.00 are incompatible. 
COBOL ISAM files are exclusively single-keyed, but 
BASIC Compiler 2.00 ISAM files are multi-keyed. 
You must use REBUILD to build properly formatted 
Key files. 


The data file formats of COBOL 1.00 ISAM and 
BASIC Compiler 2.00 ISAM are the same with two 
exceptions: COBOL 1.00 ISAM files contain no data 
dictionary and no indirection records. 


COBOL 1.00 to BASIC Compiler 2.00 
You can create a BASIC Compiler 2.00 key file from 
the COBOL 1.00 ISAM data file SINGLE.DAT by 
entering: 


REBUILD SINGLE.DAT,,1:1@ STRING 
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Note that you must specify a key field description on 
the command line (in this case, 1:10 STRING) 
because COBOL 1.00 single-key indexed files do not 
have data dictionaries. COBOL 1.00 only supports 
the ALPHANUMERIC data type, which is equivalent 
to the STRING data type in BASIC. 


The data file itself does not require any conversion to ‘ty 
be used with BASIC Compiler 2.00 ISAM. 


BASIC Compiler 2.00 to COBOL 1.00 


When converting from BASIC Compiler 2.00 format 
to COBOL 1.00 format, the data dictionary and 
indirection records must be removed from the data 
files. This is done with REBUILD. For this 
conversion you must: 


1. Convert the BASIC Compiler 2.00 data file to 
COBOL 1.00 format by removing the data 
dictionary and indirection records. For example, 
if the BASIC Compiler 2.00 file is called 
MULTI.DAT, and you want to convert it toa 
COBOL 1.00 file called SINGLE.DAT, first use 
your multi-key version of REBUILD (2.00 or 
later) and enter: 


REBUILD MULTI.DAT,SINGLE.DAT/S; 


The file SINGLE.DAT now has no data 
dictionary or indirection records. 
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2. Create anew key file in COBOL 1.00 format. 


Now, use your single-key version of REBUILD 
(1.00 or 1.10) to create a single-key formatted 
key file. Enter: 


REBUILD SINGLE.DAT,,1:19 


The key field description for the COBOL 1.00 
does not include a data type. This is because 
COBOL 1.00 ISAM assumes all field types to be 
ALPHANUMERIC. 
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The REBUILD Data-Dictionary 
Language 


When you want to give REBUILD new key 
information, you have to use the REBUILD 
data-dictionary language. This is the language you use 
in dd-file. For example, when you enter: 


REBUILD EMPLOYEE.DAT/P; 


REBUILD prints the data dictionary from the file 
EMPLOYEE.DAT. For this example, you would see 
something like this: 


RECORD EMPLOYEE; 
FIELD EMPLOYEE-NAME IS 1:3@ STRING 
KEYED BY 1; 


FIELD EMPLOYEE-ADDRESS IS 31:4@ STRING; 
FIELD SOCTAE<SECURITY IS 71210. SPRING; 
FIELD DATE-OF-EMPLOYMENT IS 81:10 STRING; 


b 


The next section explains this syntax in detail. This 
data dictionary describes a record, named 
EMPLOYEE, that contains four fields. The first field, 
named EMPLOYEE-NAME, starts in the first byte of 
the record, is 30 bytes long, and is a string. The 
phrase ““KEYED BY 1” means that the 
EMPLOYEE-NAME field is a key, and its key handle 
is 1. The second field, named 
EMPLOYEE-ADDRESS, starts in the 31st byte of 
the record, is 40 bytes long, and is also a string. The 
last two fields, SOCIAL-SECURITY and 
DATE-OF-EMPLOYMENT, start in the 71st and 
81st byte of the record, respectively, are both 10 bytes 
long, and are both strings. 


To make the DATE-OF-EMPLOYMENT field a key 
field, you would have to add the line in italics to the 
file EMPLOYEE.DD: 


RECORD EMPLOYEE; 
FIELD EMPLOYEE-NAME IS 1:38 STRING 
KEYED <6Y 24 


FIELD EMPLOYEE-ADDRESS IS 31:49 STRING; 
FIELD SOCIAL-SECURITY IS 71:10 STRING; 
FIELD DATE-OF-EMPLOYMENT IS 81:19 STRING 


KEYED BY 2; 


? 


The data dictionary does not always contain 
descriptions of fields that are not keys. In this 
example, every field was described when the original 
ISAM file was opened. If the field 
DATE-OF-EMPLOYMENT had not been described, 
it would have been necessary to add the field 
description (FIELD DATE-OF-EMPLOYMENT IS 
81:10 STRING) as well. 


Remember, changing the data dictionary and key 
information has no effect on the actual data in the file 
EMPLOYEE.DAT. REBUILD only changes the 
indexes and pointers to the field 
DATE-OF-EMPLOYMENT, it does not do anything 
to the data actually stored in that field. 


Syntax 
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Records are described by RECORD, FIELD, and 
SPLIT KEYSET statements. All statements must end 
with a semicolon. Comments are indicated by an 
asterisk in column 1. 


In the syntax diagrams that follow, entries in square 
brackets ([]) only are optional. If the optional opening 
bracket ([) is chosen, the closing bracket (|) must also 
be used. If braces enclose the square brackets (as in, 
{[}DESCENDING$ ]}), the bracket character itself 
should be used in the syntax. Comments are entered 
with an asterisk (*) in column 1, causing REBUILD to 
ignore all remaining characters on the line. 


Syntax Diagrams 


[RECORD [record-name] [{IS SEGMENTED][MINIMUM 
ALLOCATION IS integer]]]; 


FIELD [field-name] IS [[@segment]|[position]:[ size] data type 
[INSENSITIVE ]]; 


[KEYED BY key-number {[}DESCENDING{]}{/[ DUPLICATES 
ALLOWED]... ; 


SPLIT KEYSET keyset-number [IS] field-name | key-number 
{[}{ DESCENDING} ]} ... [DUPLICATES ALLOWED]; 


RECORD 
Statement 


v Purpose: The RECORD statement is used to set global file 
options. 


Format: [RECORD [record-name]| [[IS 
SEGMENTED][MINIMUM ALLOCATION IS 
integer]||]; 


Remarks: The RECORD statement is optional and only one 
RECORD statement can be given for each record. 
The three options are record-name, SEGMENTED, 
and MINIMUM ALLOCATION. 


record-name An optional identifying name. 


SEGMENTED The data file contains segmented 
records. 


YY MINIMUM ALLOCATION 
Specifies the minimum record 
size allocated from the data file. 
As described under Rdes(3) in 
the ‘“‘Record Description”’ 
section, MINIMUM 
ALLOCATION can be used to 
minimize data file fragmentation 
when IREWRITE is used with 
variable length records. Setting 
MINIMUM ALLOCATION 
equal to the largest record size in 
the file minimizes fragmentation. 


FIELD 


Statement 
Purpose: The FIELD statement describes each field in the ‘oa 
record. 


Format: FIELD [field-name]| IS [[@segment]|[position]:[size] 
data type [INSENSITIVE ]]; 


Remarks: 


field-name 


(segment 


position 


size 


datatype 


INSENSITIVE 
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Name of field; maximum 40 
characters; enclose the name in 
double quotes (‘‘ field-name ’’). 


Segment number of this field. If 
omitted, the segment number 
defaults to 1. 


Position from start of the record. 


Size of data field in bytes. 


REBUILD supports the following 
data types: 


DOUBLE 
INTEGER 
NUMERIC 
SINGLE 
STRING. 


This flag makes ISAM ignore 
differences in case in string-based 
data types (for example, the 
values ‘“‘FiRst”’ and “‘first’”” would “a 
be equal). 


FIELD 
Statement 


At least one FIELD statement must be given for 
each record; multiple FIELD statements can be used. 
It is recommended that all fields in a record be 
named, even though REBUILD only requires that 
key fields be named. Naming all fields saves time if 
the data dictionary is changed later on. 


KEYED BY 
Clause 


Purpose: The optional KEYED BY clause makes a specific 
field into a key. 


Format: [KEYED BY key-number 
{[}{DESCENDING{]|}{/ DUPLICATES 


ALLOWED ]|I... ; 
Remarks: 
key-number The key handle. This number 
can range from 1 to n where n is 
the number of keys. 
DUPLICATES ALLOWED 


Allows two or more records to 
have the same key value. 
Without this parameter, an error 
is returned when a record is 
inserted that has the same key 
value as another record. 


DESCENDING Inverts the meaning of 
comparisons performed in the 
field. The result is that records 
are inserted in descending order 
instead of ascending order. 
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SPLIT KEYSET 
Statement 


& Purpose: The SPLIT KEYSET statement defines split keys. 


Format: SPLIT KEYSET keyset-number [IS] field-name | 
key-number {{} DESCENDING} ]} ... [DUPLICATES 
ALLOWED]; 


Remarks: 


key-number The key handle. This number 
can range from 1 to n where n is 
the number of keys. 


field-name or key-number 
The same field name used to 
identify the field in the FIELD 
statement. If no name was given 
&Y in the FIELD statement, 
key-number can be substituted 
for field-name. 


DESCENDING _ Inverts the meaning of 
comparisons performed in the 
field. The result is that records 
are inserted in descending order 
instead of ascending order. 


DUPLICATES ALLOWED 
Allows two or more records to 
have the same key value. 
Without this parameter, an error 
is returned when a record is 
inserted that has the same key 
© value as another record. 


This statement is optional; multiple SPLIT KEYSET 
statements can also be used. 
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SPLIT KEYSET 
Statement 
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Suppose you have a data file named BUYER.DAT, 
and you want to add a new field and a new key to 
your record description. First, to put a copy of the 
data dictionary into a file that you can edit, enter: 


REBUILD BUYER.DAT/P ;>BUYER.DD 


REBUILD reads the binary data dictionary from 
BUYER.DAT and writes the data dictionary—in the 
REBUILD data-dictionary language—to the file 
BUYER.DD. In this example, the BUYER.DD file 
looks like this: 


FIELD NUMBER IS 1:5 STRING 

KEYED BY 1; 
FIELD NAME IS 6:28 STRING 

KEYED BY 2 DUPLICATES ALLOWED; 
FIELD CITY IS 26:28 STRING 

KEYED BY 3 DUPLICATES ALLOWED; 
FIELD PROCESS-CODE IS 51:1 STRING; 


Now, you want to identify a new field containing zip 
codes and use that as a key. You also want to create 
a split key that contains the city field and the zip 
code field. Edit the file BUYER.DD, adding the new 
information like this: 


FIELD NUMBER IS 1:5 STRING 
KEYED BY 1; 
FIELD NAME IS 6:28 STRING 
KEYED BY 2 DUPLICATES ALLOWED; 
FIELD CITY IS 26:28 STRING 
KEYED BY 3 DUPLICATES ALLOWED; 
FIELD ZIP-CODE IS 46:5 STRING 
KEYED BY 4 DUPLICATES ALLOWED; 
FIELD PROCESS-CODE IS 51:1 STRING; 
SPLIT KEYSET 5 IS CITY ZIP-CODE DUPLICATES ALLOWED; 


SPLIT KEYSET 
Statement 


If you enter the following command line: 
REBUILD BUYER.DAT ,NEWBUYER.DAT ,BUYER.DD 


the file NEWBUYER.DAT will have a data 
dictionary like the one in the new BUYER.DD 
above, and REBUILD builds a key file 
NEWBUYER.KEY which contains the new key 
information. 


Any programs that had used BUYER.DAT should 
now be updated to uue NEWBUYER.DAT. 
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Appendix E. Using the Library Manager 


The Library Manager 


The IBM Library Manager allows you to construct and 
edit object module libraries. Object files and other 
library files can be added to a library and object - 
modules can be removed and erased from a library. 


Command Line Format 


The format of the command line is: 


LIB [Jibrary-file | pagesize|operations 
[ ,[Jist-file]|[|,[newlib]][;]] 


library-file is the name of a library file. 
pagesize is an optional switch of the form, 
“/pagesize:N” or “/p:N” 
where WN equals: 
16, 32088, 325: 256, or 512. 


By default, libraries under IBM DOS 
are always multiples of 512 byte 
blocks. Object modules always start at 
the beginning of a new block. A block 
is also called a page. If the size of the 
object module is less than a block, the 
rest of the block is filled with null 
bytes. 


operations 


list-file 


When you specify the pagesize in the 
command line, the library being created 
or modified contains N byte pages. 


The size of the library that you are 
creating or modifying can increase 
when you specify larger pagesize 
values. However, the time it takes to 
link the library decreases when you use 
larger pagesizes. 


The default value for the pagesize 
switch is 512 if the library file is being 
created, or the current pagesize if the 
library file is being modified. 


Note: Version 2.30 of the Linker 
is included with this version of the 
BASIC Compiler 2.00. Previous 
versions of the Linker cannot 
recognize pagesizes less than 512. 
Therefore, you should always use 
the latest version of the Linker. 


is a list of operations to perform. This 
list contains an operator plus the name 
of the file you are adding. The default 
is an empty list; no changes occur. See 
‘““Operators,”’ later in this section, for a 
description of the operators. 


is a filename where a cross reference 
listing will be placed. No default 
extensions are used. 


The default for [, /ist-file| is no list file; 
a cross reference is not generated. You 
are asked for this entry if it is left 
empty. 


newlib defines the name of a library file to be 
created with the changes specified by 
the operations. The default is the same 
name as the library file. If you use the 
default, the original file is renamed to 
have the extension ‘‘.BAK’”’ instead of 
* Cie 


The command line can be broken by a carriage return 
at any point. You are asked for the remaining parts of 
the command line. If a semicolon ends any field after 
the library file name, the remaining fields take on their 
default values. If you just specify LIB, you are asked 
for all entries. 


Note: You can have a device identification before 
any of the entries that you specify in the 
command line. 


Operators 


The operators recognized by the Library Manager are: 


+ Add the contents of an object file or a 

library file. 
= Erase an object module. “y 
. Remove an object module into a file whose 


name is the specified module name plus the 
extension “.OBJ’’. 


These individual operators can be combined to 
perform more complex operations. For example: 


—+ Replace an object module with the 
contents of the object file of the same 
name (plus ‘‘.OBJ’’). 


—* Remove an object module and at the same 
time erase it. 


Many operations may be performed at once. If you 
want to specify operations on more than one line, 
follow your last operation with an & and a carriage 
return. 


The operations are performed in the following order: 
1. Erasures and removals 


2. Additions 


Erasures and removals are performed in the order in 
which the specified object modules occur in the 
library. Additions are performed in the order that you 
specified. 


Examples: 


To add the file TEST.OBJ to the library BASIC.LIB 
without producing a cross-reference, type: 


LIB BASIC.LIB+TEST.OBJ; 


Note that the following is the same as the preceding 
example: 


EIS BASIC+TES@s 


Extensions are optional, and the default to .OBJ if 
omitted. If you are using a library file that is in the 
operations list, you must specify the .LIB extension. 


To erase TEST from BASIC.LIB, type: 


bin emo. C-TEST; 


To replace TEST in the library with a newer version, 
type: 


EIS; BaAslC-+TESte 
Note that the following also have the same effect: 
LIB BASIC-TEST+TEST.OBJ; 


LIB BASIC+TEST tear, 


If you want to make the same change, but put the 
changes in a new library called BASNEW.LIB, any of 
the following work: 


LIB BASIC-+TEST, ,BASNEW 
LIB BASIC-TEST+TEST, ,BASNEW 
LIB BASIC+TEST-TEST, ,BASNEW 


If you want to create a library of object modules, 
type: 


LIB MYSUBS+FILE1.0OBJ+FILE2.0BU+...+FILEN.OBJ. 


You are asked for the listing file. 


Response File 


You can place all of your responses to the prompts in 
a response file. The Library Manager is instructed to 
read the responses from the response file by the 
following: 


LIB @RESP.TXT 


where RESP.TXT is the filename containing the 
responses. 


Note: RESP.TXT was chosen as an example. 
Any valid DOS file name can be used. 


Cross-Reference Lists 


Two types of cross-references are generated: 


e Alphabetic list 


& e Object module list. 


The alphabetic list contains the public symbol 
followed by the object file. For example, the 
cross-reference for BASCOM20.LIB contains: 


PME As 'sls se ss SWAP sf SWAP 
os SWAP 7 ere SWAP 


The second list contains the object file “SWAP,” the 
offset value, and the code and data size in 
hexadecimal. 


SWAP Offset: 2197@H Code and data size: 4FH 
$SWPA $SWPB &SWPC &SWPD 


Library Manager Error Messages 


Nonrecoverable Errors 


MESSAGE: PROBABLE 
CAUSE: “y 
aborted by user You did not want 


to create library 


alignment factor too small Library larger 
than 
(pagesize)*64KB 

cannot create new library Directory full or 
name bad 

cannot open indirect file Response file does 
not exist 

cannot open VM.TMP Directory full 

cannot read from VM A problem in the 
Library Manager 

cannot rename old library Bad file name 

cannot reopen library A problem in the 
Library Manager 

cannot write to VM Diskette full 

command syntax error Typographical 
error 


error writing to cross reference file 
Diskette or fixed 


disk full a“ 


MESSAGE: 


error writing to new library 


fetch: not allocated 


free: not allocated 


insufficient memory 


internal failure 


invalid file name extension 


invalid library 


invalid library name extension 


invalid object module... 


mark: not allocated 


no more virtual memory 


PROBABLE 
CAUSE: 


Diskette or 
fixed disk full 


A problem in 
the Library 
Manager 


A problem in 
the Library 
Manager 


Not enough 
memory for 
Library 
Manager 


A problem in 
the Library 
Manager 


Extension 
specified is not 
-OBJ or .LIB 


File is nota 
library file 


Name does not 
end in .LIB 


Corrupt object 
module 


A problem in 
the Library 
Manager 


Too many 
public symbols 


MESSAGE: 


syntax error 


syntax error (bad file spec) 


syntax error (bad input) 


syntax error (switch name expected) 


syntax error (switch value expected) 


too many symbols 


unexpected EOF on command input 


unknown switch 


write to extract file failed 


write to library file failed 


PROBABLE 
CAUSE: 


Typographical 
error 


Typo specifying 
file name “ 


Illegal character 
in input 


Name not 
found after / 


Illegal character 
after : 


Too many 
public symbols 


Unexpected 
EOF on 
response file 


Unknown name 
after / 


Diskette or 
fixed disk full 


Diskette or 
fixed disk full 


Recoverable Errors. 


MESSAGE: PROBABLE 

CAUSE: 
& cannot create extract file... Directory full 
cannot create listing... Bad file name 


or directory full 


extension illegal—file ignored Extension is not 
.LIB or .OBJ 

invalid format...; file ignored Input file is not 
an object or 
library 

invalid library header Input file is not 
a library 

module not in library; ignored Module to 
extract or delete 

& does not exist 
page size too small—ignored Value of page 


size switch is 
less than 16 
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Glossary 


application program. A program written by or fora 
user that applies to the user’s work. For example, a 
payroll application program. 


argument. A value that is passed from a calling 
program to a function. 


arithmetic overflow. When the result of an operation 
exceeds the capacity of the intended unit of storage. 


ASCII. American National Standard Code for 
Information Interchange. An ASCII file is a text file 
that uses ASCII codes to represent each character. 


that can be used in case of a malfunction or loss of 


Y backup. Pertaining to a system, device, file, or facility 
data. 


BASIC. Acronym for Beginners All-purpose Symbolic 
Instruction Code, a programming language. 


binary. Pertaining to a condition that has two possible 
values or states. Also, refers to the base 2 numbering 
system. 


buffer. An area of storage that is used to compensate 
for a difference in rate of flow of data, or time of 
occurrence of events, when transferring data from one 
device to another. Usually refers to an area reserved 

& for I/O operations, into which data is read or from 
which data is written. 


bug. An error in a program. 
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byte. The representation of a character in binary. 
Eight bits. 


call. To bring a computer program, a routine, or a 
subroutine into effect, usually by specifying the entry 
conditions and jumping to an entry point. “ 


child process. The process of loading and executing a 
program from another program. For example, during 
program execution, BASIC, the parent program, loads 
and executes another program using the SHELL 
statement. 


code. To represent data or a computer program in a 
symbolic form that can be accepted by a computer; to 
write a routine. Also, loosely, one or more computer 
programs, or part of a program. 


comment. A statement used to document a program. 
Comments include information that may be helpful in 
running the program or reviewing the output listing. 


compile. To translate a computer program written in 
problem-oriented language into machine-oriented 
language. 


compiletime. That period of time during which the 
compiler is executing, during which it compiles a 
BASIC source file and creates an object file. 


debug. To find and eliminate mistakes in a program. 


default. A value or option that is assumed when none 
is specified. 


delimiter. A character that groups or separates words 
or values in a line of input. 


device coordinates. In computer graphics, coordinates 
that are used to scale an image to suit the actual 
dimensions of the device. 
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directive. A compiler metacommand. 


directory. A table of identifiers and references to the 

corresponding items of data. For example, the 

directory for a diskette contains the names of files on 

the diskette (identifiers), along with information that 
& tells DOS where to find the file on the diskette. 


disabled. A state that prevents the occurrence of 


certain types of interruptions. 


DOS. Disk Operating System. In this book, refers 
only to the IBM Personal Computer Disk Operating 
System. 


dummy. Having the appearance of a specified thing 
but not having the capacity to function as such. For 
example, a dummy argument to a function. 
dynamic. An event occurring at the time of execution. 
YY dynamic array. An array that can be redimensioned. 
echo. To reflect received data to the sender. For 
example, keys pressed on the keyboard are usually 
echoed as characters displayed on the screen. 


edit. To enter, modify, or delete data. 


enabled. A state of the processing unit that allows 
certain types of interruptions. 


end of file (EOF). A “‘marker’’ immediately following 
the last record of a file, signaling the end of that file. 


w EOF. See “end of file.”’ 
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event. An occurrence or happening; in IBM Personal 
Computer Advanced BASIC, refers particularly to the 
events tested by COM(n), KEY(n), PEN, and 
STRIG(n). 


execute. To perform an instruction or a computer 


program. ‘a, 


external reference. A variable name or label in one 
module that is referenced in another module. External 
labels are the entry points into modules. 


folding. A technique for converting data to a desired 
form when it doesn’t start out in that form. For 
example, lowercase letters may be folded to uppercase. 


format. The particular arrangement or layout of data 
on a data medium, such as the screen or a diskette. 


form feed (FF). A character that causes the print or 
display position to move to the next page. 


function. A procedure that returns a value depending “& 
on the value of one or more independent variables in a 
specified way. More generally, the specific purpose of 

a thing, or its characteristic action. 


garbage collection. Synonym for housecleaning. 
global reference. Same as external reference. 

hard copy. A printed copy of machine output in a 
visually readable form. 

housecleaning. When BASIC compresses string space 


by collecting all of its useful data and frees up unused 
areas of memory that were once used for strings. 


Glossary-4 


instruction. In a programming language, any 
meaningful expression that specifies one operation and 
its operands, if any. 


integer. One of the numbers O, +1, +2, +3.... 


integrity. Preservation of data for its intended 
purpose; data integrity exists as long as accidental or 
malicious destruction, alteration, or loss of data are 
prevented. 


interface. A shared boundary. 


interpret. To translate and execute each source 
language statement of a computer program before 
translating and executing the next statement. 


interrupt. To stop a process in such a way that it can 
be resumed. 


invoke. To activate a procedure at one of its entry 


points. 


w ISAM. Indexed Sequential Access Method. Allows 
access to files according to the contents of the records 
in the files. Provides increased speed in accessing 
files, especially large files. 


K. When referring to memory capacity, two to the 
tenth power or 1024 in decimal notation. 


keyword. One of the predefined words of a 
programming language; a reserved word. 


library. A set of routines in a file on diskette. 
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linking. The process by which the Linker program 
combines separate modules, resolves all external 
references by searching the appropriate library, and 
creates a single executable (.EXE) file on diskette. 


linktime. That period of time during which the Linker 


is running. “ 


location. Any place in which data or machine 
instructions may be stored. 


loop. A set of instructions that may be executed 
repeatedly while a certain boolean condition prevails. 


M. Mega; one million. When referring to memory, 
two to the twentieth power; 1,048,576 in decimal 
notation. 


metacommand. A statement that supplies information 
to the compiler but which usually does not directly 
result in executable code. For the BASIC Compiler 
2.00, some of the metacommands are $INCLUDE, 
$LINESIZE, $PAGE, $PAGESIZE, and $TITLE. 


mnemonic. A symbol chosen to assist the human 
memory; for example, an abbreviation such as ““MPY”’ 
meaning “‘multiply.”’ 


module. A fundamental unit of code. There are several 
types of modules, including object and executable 
modules. The compiler creates object modules that 
are later manipulated by the Linker. Your final 
executable program is an executable module. 


nest. To incorporate a structure of some kind into 
another structure of the same kind. For example, you 
can nest loops within other loops, or call subroutines “ 
from other subroutines. 
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notation. A set of symbols, and the rules for their use, 
for the representation of data. 


null. Empty, having no meaning. In particular, a 
string with no characters in it. 


object file. Output from a compiler that is executable 
machine code or is suitable for processing to produce 
executable machine code. 


offset. The number of units from a starting point (in a 
record, control block, or memory) to some other 
point. For example, in BASIC the actual address of a 
memory location is given as an offset in bytes from the 
location defined by the DEF SEG statement. 


on-condition. An occurrence that could cause a 

program interruption. It may be the detection of an 

unexpected error, or of an occurrence that is expected, 

but at an unpredictable time. 

operating system. Software that controls the execution 
Y& of programs; often used to refer to DOS. 

operation. A well-defined action that, when applied to 


any permissible combination of known entities, 
produces a new entity. 


overflow. When the result of an operation exceeds the 
capacity of the intended unit of storage. 

parameter. A name in a procedure that is used to refer 
to an argument passed to that procedure. 


physical coordinates. See ‘“‘device coordinates.”’ 


prompt. A question or symbol the computer displays 
& when it needs you to supply information. 


Glossary-7 


range. The set of values that a quantity or function 
may take. 


real-time. Pertaining to the manipulation of data that 

is required or generated by some process while that 

process is in operation; usually the results are used to 

influence the process while it is occurring. ry 


record. A collection of related information, treated as 
a unit. For example, in stock control, each invoice 
might be one record. 


recursive. Pertaining to a process in which each step 
makes use of the results of earlier steps, such as when 
a function calls itself. 


relocatable. A module is relocatable if the code within 
it can be “‘relocated”’ and run at different locations in 
memory. Relocatable modules contain labels and 
variables represented as offsets relative to the start of 
the module. These labels and variables are said to be 
‘“‘code relative.’’ During the linking step, the Linker 
associates an address with the start of the module, and 
then computes an absolute address that is equal to the » 
associated address plus the code-relative offset for 
each label or variable. These new computed values 
become the absolute addresses that are used in the 
executable file. 


routine. Executable code residing in a module. More 
than one routine may reside in a module. 


runtime. That period of time during which a 
previously compiled and linked program is executing. 
By convention, runtime refers to the execution time of 
your program and not to the execution time of the 
compiler or the Linker. 


runtime module. BASRUN.EXE — a module 
containing most of the routines needed to implement 
the BASIC language. A library routine usually 
corresponds to a feature or subfeature of the BASIC 
language. 
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The runtime module is unusual in that it is an 
executable .EXE file, and must be accessible on disk 
when you execute your final .EXE file. 


runtime support. The body of routines that may be 
linked to your compiled object file. These routines 
implement various features of the BASIC language. 
The BASCOM20.LIB and BASRUN20.LIB libraries, 
along with the runtime module, all contain runtime 
support routines. 


source. A BASIC program in ASCII format. Usually 
this term is used to refer to the program that is input 
to the compiler. The compiler translates this source 
and creates as output a new file called an object file. 


stack. A method of temporarily storing data so that 
the last item stored is the first item to be processed. 


statement. A meaningful expression that may describe 
or specify operations and is complete in the context of 


Y the BASIC programming language. 


static array. An array that cannot be redimensioned. 


syntax. The rules governing the structure of a 
language. 


trap. A set of conditions that describe an event to be 
intercepted and the action to be taken after the 
interception. 


unbound global reference. Same as unresolved external 
reference. 


unresolved external reference. An external reference 
& in a module that is not declared in that module. The 
Linker tries to “‘resolve’’ this situation by searching for 
the declaration of that reference in other modules. 
These other modules are usually library modules. If 
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the variable or label is found, the address associated 
with it is substituted for the reference in the first 
module, and is then said to be “‘resolved.’? When a 
variable is not found, it is said to be ‘“‘undefined.”’ 


External references that are not resolved as part of the 
linking process can cause unpredictable results when 
you run your program. 


world coordinates. A system that allows you define the 
dimensions of an image without regard for the physical 
size of the display device. 
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Special Characters 


;on command line 4-7 
! 7-8 
$LIST 4-26 
S$MODULE metacommand, 
use in modular 
programming C-18 
S$OCODE 4-26 
$SUBTITLE 4-26 
$TITLE 4-26 
/E and other compiler 
parameters 4-9 
See also compiler 
parameters 
% 7-8 
# 7-8 


A 


A: 6-8 
/A parameter 4-14 
A: 6-8 
absolute form for specifying 
coordinates 6-29 
access method D-1 
index D-1 
sequential D-1 
accuracy 7-7 
adapters 
communications A-16 
display 6-20 
printer A-16 


addition 8-4 
addressability, parameter C-27 
agreement, license 1-8 
aliasing variables C-8 
allocation, minimum 
record D-19 
alphabetic characters 5-6 
alternate library parameter - 
/O 4-18 
AND 8-8 
append 6-16 
argument expressions, assembly 
language interface C-29 
argument, definition of C-5 
arithmetic operators 8-4 
array arguments, passing C-7 
array descriptors, 
dynamic A-13 
array elements, passing C-6 
array order parameter - 
/R 4-18 
array passing, assembly 
language interface C-30 
arrays 4-16, 4-18, 5-16, 7-15 
defining 7-15 
dimensioning 7-15 
dynamic 7-17 
elements in 7-15 
Static 7-17 
subscripts in 7-15 
assembly language interface, 
ISAM D-74 
assembly language subprogram 
requirements C-19 
argument expressions C-29 
CALL statement C-25 
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CALLS statement C-26 
code segment C-23 
const segment 
requirements C-24 
data segment 
requirements C-24 
debugging C-32 
formal parameters C-29 
stack segment 
requirements C-25 
structuring C-21 

attributes 6-25 

AUTO 5-11 


available bytes 3-7, 3-21, 4-23 


B 


B: 6-8 
B-trees, ISAM D-3 
background 6-22 
backing up diskettes 2-4 
.BAS extension 1-6, 4-5 
BASCOM20.LIB 4-20 
See also /O parameter 
BASIC data record D-13 
BASIC diskette, contents 
of 2-3 
BASIC program editor 5-17 
BASRUN20.EXE 4-19 
See also runtime module 
batch file 3-26 
beeping from the 
computer 5-16, 5-18, A-15 
bits per pixel 6-25 
blanks 5-8 
book 
general information iii 
how to use iii 
related books viii 
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boolean operations 8-7 
border screen 6-22 


Boundary error indicator D-88 


branch 6-12 
buffer A-15 
communications 4-15 
keyboard A-15 
building a new file, 
ISAM D-87 
built-in functions 
See functions 
bytes available 3-7, 3-13, 
3-21, 4-23 
bytes free 3-7, 3-13, 3-21, 
4-23 


C 


/C parameter 4-15 
call by reference C-29 
CALL statement, assembly 
language interface C-25 
calling assembly language 
subprograms C-19 
calling by reference C-5 
calling by value C-5 
calling subprograms C-3 
CALLS statement, assembly 
language interface C-26 
cassette I/O 5-12 
cassette module 2-3 
CHAIN 4-20 
chaining files C-17 
changes, software 
See summary of changes 
changes, summary of ix 
changing key information, 
ISAM D-82 
changing key information, 
REBUILD D-90 


character set 5-6 
characters, filename 6-4 
check point function, 
ISAM D-50 
clipping 6-29 
code parameter - /A 4-14 
code segment requirements, 
assembly language 
interface C-23 
code, listing object 4-14 
codes, ISAM 
See ISAM Codes 
COLOR 
in graphics modes 6-27 
in text mode 6-22 
color attributes 6-25 
COM(n) 5-11 
command line 
compiler 4-6 
command line arguments, 
REBUILD D-83 
command line, 
REBUILD D-83 
commands not 
implemented 5-11 
comments 5-6 
COMMON 4-20 
COMMON blocks, 
named C-12 
COMMON statement ISAM, 
using D-15 
COMMON statement, use 
of D-23 
communications B-1 
communications devices 6-8 
communications file, 
opening B-1 
communications module 2-3 
communications parameter - 
/C 4-15 
comparison to interpreter 5-10 
comparisons 
numeric: 8-6 


String 8-7 
compatibility, software iv 
compile, link, and go 3-26 
compiled program, advantages 
of 1-6 
compiler 1-3 
BASIC Compiler 2.00 
package 2-3 
command line 4-6 
definition of 1-3 
using 4-4 
compiler parameters 4-9 
convention 4-12 
/T 4-13 
/4 4-12 
error trapping 4-10, 5-12 
/E 4-10 
/X 4-11 
event trapping 4-11, 5-11 
/V 4-11 
/W 4-12 
special code 4-14 
/A 4-14 
/C 4-15 
/D 4-16, 5-12, 5-15 
JN 4-17 
/O 4-18 
/R 4-18 
/S 4-18 
summary chart 4-21 
compiler termination 
codes 3-26, 4-24 
compiling 3-4, 3-11, 3-19, 4-3 
finishing 4-23 
prompts 4-4 
sample listing 4-26 
Starting 4-4 
starting with batch 
file 3-26 
compiling independent 
modules C-1 
compiling process, description 
of 1-7 
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complement, logical 8-8 cursor movement keys 5-18 
complement, twos 8-10, 8-11 

composition D-2 

compressing a data file, 


ISAM D-89 D 
compressing data files, 
REBUILD D-83 “Ye 
eo = /D parameter 4-16, 5-12, 5-15 
COMI: A-16 ; 
damaged file ISAM, 
COM2: 6-8 
unrecoverable D-88 
COM2: A-16 d d fil aa D-87 
CON 6-8 amaged file, replacing D- 


damaged key files, 
rebuilding D-82 
data base ISAM, operations 


concatenation 8-14 
config.sys file 5-19 
conjunction 8-8 
const segment requirements, on D-35 
assembly language Data column on compiler 
oe et ing error message 
tants, string 4-18, 7-13 ‘ 
sa ag ISAM D-89 


data dictionary, ISAM D-3 
data file, compressing D-89 
data file, ISAM D-2 
contract, license 1-8 : 
control requests, ISAM data record, BASIC D-13 ‘a 
See ISAM ICONTROL data records, types of D-4 
data segment requirements, 
assembly language 
interface C-24 
data segment, maximum size 
of:.4x 
data type sizes D-73 


contents of compiler 
package 2-3 


Requests 
control signals, I/O B-5 
convention parameters 4-12 
See also compiler 
parameters, convention 


converting 
one numeric precision to data types, ISAM 
another 7-10 : er ISAM ape Types 
coordinates 6-29 ata-dictionary language, 
corrupt file, ISAM D-87 REBUILD D-94 


dd-file, REBUILD D-85 


fil -1 
corruption, file D-12 debug parameter - /D 4-16, 


creating a key descriptor D-20 


eae 5-12, 5-15 
cross-reference list, library 2 
manager E-7 debugging 4-7 
Ctrl keys 5-18 using a source listing 4-9 a) 
Ctrl-Break 4-24, 5-18 using error trapping 
parms 4-10 


current directory 6-11 


current record D-6 using the compiler 4-30 


using the interpreter. 4-30 
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debugging assembly 
language C-32 arithmetic 5-14 
declaring variable types 7-7, dynamic array 
7-8 descriptors A-13 
default directory 6-11 dynamic arrays 7-17 
default filenames 4-8 
defining arrays 7-15 
DELETE 5-11 
demonstration program 3-3 E 
compiling 3-4, 3-11, 3-19 
running 3-10, 3-18, 3-25 


double-precision 


descriptor, string A-12 
descriptors, dynamic 
array A-13 
detecting errors 4-30 
device coordinates 6-30 
device driver 6-9 
device name 6-5, 6-7 
devices 6-7 
communications 6-8 
keyboard 6-7 
printer 6-7 
screen 6-7 
storage 6-8 
support 6-9 
dictionary ISAM,data D-3 
dimensioning arrays 7-15 
directory types 6-11 
disjunction 8-8 
disk I/O 6-13 
disk space, running out 
of D-87, D-88 
Disk storage error D-88 
diskettes in package 2-3 
display adapters 6-20 
display pages 6-23 
display screen, using 6-20 
display screens vil 
display, soft key 6-22 
displays vii 
division 8-4 
double-precision 7-7 


/E parameter 4-10 
EDIT 5-11 
editor 5-17 
elements of an array 7-15 
entry points, ISAM D-74 
EOF 6-15 
equivalence 8-8 
EQV 8-8 
error detection 4-30 
error message ISAM, data 
dictionary D-89 
error messages, library 
manager E-8 
error trapping 4-10, 5-12 
See also compiler 
parameters, error trapping 
errors, I/O B-9 
errors, Subprogram calling C-8 
event trapping 4-11, 5-11 
See also compiler 
parameters, event trapping 
exclusive or 8-8 
.EXE file, size of x 
executable statements 5-5 
execution speed 1-6, 3-11 
exponentiation 8-4 
expression evaluation 5-14 
expressions 
numeric 8-3 
string 8-14 
expressions, passing C-8 
extension, filename 4-5, 6-4 
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.BAS 4-5 

.LST 4-6 

OBJ 4-5 
extensions, filename 

See filename extensions 
external module, definition 
of C-2 


F 


false 8-6, 8-8 
field description, ISAM D-19 
field parameters ISAM, 
key D-20 
FIELD Statement D-98 
FIELD statement ISAM, 
using D-14 
FIELD statement, REBUILD 
utility D-98 
file 6-3 
closing D-87 
definition of 6-3 
naming 6-4 
number 6-3 
opening 6-3 
random 6-16 
sequential 6-14 
file access D-1 
index D-1 
sequential D-1 
file corruption D-12 
file handle, ISAM D-13 
file opening 
See ISAM file 
file opening modes, 
ISAM D-58 
file position, locating D-64 
file type 1-5 
object 1-5 
run 1-5 
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source 1-5 

filename 6-4, 6-5 
description of 6-4 
rules 6-4 

filename extensions 1-6 
.DAT, ISAM D-2 
KEY, ISAM D-2 
SYS 5-19 


OBJ 1-6, 4-5 
creating, rules 6-4 

files, maximum number 5-19 
first time through 2-4 
fixed-field record, ISAM D-4 
fixed-point 7-4 
flag fields ISAM, use of D-21 
floating-point 7-4 
FOR...NEXT 4-13 
Force switch (/f), 

REBUILD D-86 
foreground 6-22 
formal parameter, definition 

of C-5 
formal parameters, assembly 

language interface C-29 
formatting diskettes 2-4 
formatting numeric 

output 7-12 
function ISAM, 

checkpoint D-50 
functions 8-11, 8-15 
functions, I/O B-2 


G 


general device I/O 6-3 
general information iii 
generating a new file D-87 
GET (files) 6-19 


global variable C-10 included file, ISAM D-46 


GOSUB 4-16 index access method D-1, D-3 
graphics 6-20 indirection record, ISAM D-19 
graphics modes 6-24 INEXT D-57 


INPUT 4-14, 5-16, 5-17 
input and output 6-3 
general device 6-3 

H input control signals, I/O B-6 
input file mode 6-15 

input files 

compiler 1-6 

hardware requirements vi input variable C-5 


ee a, INPUTS$ function B-3 
hierarchy of operations 8-12 installing ISAM D-5 
high resolution 6-28 integer 7-4, 7-7 


Home key 5-18 integer division 8-4 
how to format output 7-12 integer variables 5-16 
how to use book iii interface ISAM, assembly 
language D-74 
intermodule subprogram 


call C-3 
I interpreter, definition of 1-3 
intramodule subprogram 

& call C-3 

I/O errors B-9 intrinsic functions 

I/O functions B-2 See functions 

I/O statements 6-13 IOPEN D-58 

I/O, cassette 5-12 IPREV D-60 

I/O, communications B-1 IREAD D-61 

I/O, sample program B-4 IRESTOREFP D-62 

IBM BASIC product, IREWRITE D-63 

components iii ISAM D-1 

IBMCAS.OBJ 2-3 See also ISAM file 

IBMCOM.OBJ 2-3 definition of D-1 

ICLOSE D-49 flag fields D-21 

ICLOSE, using D-88 installing D-5 

ICONTROL D-50 interface D-4 

IDELETE D-51 parameters D-13 

IDREAD D-52 terms and concepts D-13 
& IGETDP D-54 using D-1 

IGETKD D-55 ISAM application D-4 

IMP 8-8 basic steps D-5 

implication 8-8 writing D-4 
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ISAM Assembly language 
interface D-74 
example of D-75 
status codes D-75 
ISAM Codes D-70 
ISAM data record D-13 
ISAM Data Types D-73 
ISAM file D-2 
See also ISAM 
closing D-12 
corrupted D-87 
creating D-3 
data file D-2 
examples D-23 
included file D-46 
key file D-2, D-3 
opening D-6 
rules of usage D-2 
special types D-3 
ISAM ICONTROL 
Requests D-73 
ISAM Interrupt 21H D-74 
ISAM library D-1 
ISAM Open Modes D-72 
ISAM operations D-7 
ISAM REBUILD utility D-82 
changing key 
information D-82, D-90 
closing a file D-87 
command line 
arguments D-83 
command line, using D-83 
compressing a data 
file D-89 
compressing data 
files D-83 
damaged key files D-82 
data dictionary error D-89 
data-dictionary 
language D-94 
dd-file D-85 
key-des D-84 
redirecting output D-90 
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replacing damaged key 
file D-87 
single-key description D-84 
source file D-83 
switches D-85 
syntax D-96 
target file D-84 
unrecoverable damaged 
file D-88 
ISAM Records D-4 
field description D-19 
fixed-field D-4 
indirection D-19 
looking for D-6 
minimum allocation D-19 
nonsegmented D-4 
operating on D-7 
record description D-18 
segmented D-4, D-16 
variable-field D-4 
ISAM Seek Modes D-72 
ISAM Status Indicators D-70 
ISAM Subroutines D-48 
ICLOSE D-49, D-76 
ICONTROL D-50, D-76 
IDELETE D-51, D-77 
IDREAD D-52, D-77 
IGETDP D-54, D-77 
IGETKD D-55, D-78 
INEXT D-57, D-78 
IOPEN D-58, D-79 
IPREV D-60, D-80 
IREAD D-61, D-80 
IRESTOREFP D-62, D-80 
IREWRITE D-63, D-80 
ISAVEFP D-64, D-81 
ISEEK D-65, D-81 
ISIZEOF D-68, D-81 
IWRITE D-69, D-81 
structure of D-76 
ISAM, indirection 
records D-19 
ISAVEFP D-64 


ISEEK D-65 
ISIZEOF D-68 
IWRITE D-69 
IWRITE, using D-88 


K 


key descriptor, creating D-20 

key display, soft 6-22 

Key field parameters 
ISAM D-20 

key file, ISAM D-2, D-3 

key flags D-21 

key handle, ISAM D-15 

key handles conventions, 
ISAM D-21 

KEY(n) 5-11 

key-des parameter, 
REBUILD D-84 

keyboard buffer A-15 

KEYED BY Clause D-100 

KEYED BY clause, REBUILD 
utility D-100 

keys, program editor 5-17 


L 


language additions 
See summary of changes 

language differences 5-10, 

5-12 
last point referenced 6-30 
length of line 5-21 
length of strings 5-20 
lexical parameters 4-12 


See also compiler 
parameters, convention 
libraries 3-9, 3-16, 3-23 
libraries of subprograms C-14 
libraries prompt 3-9, 3-16, 
3-23 
library manager E-1 
command line format E-1 
cross-reference list E-7 
error messages E-8 
operators E-4 
response file E-6 
library manager command line 
format E-1 
library manager cross-reference 
list E-7 
library manager error 
messages E-8 | 
library manager operators E-4 
library manager response 
file E-6 
library of modules, 
building C-16 
license agreement 1-8 
line command 
for compiler 4-6 
line editor 5-17 
line format 5-3 
BASIC program 5-3 
on screen 6-21 
line length 5-21 
line list 1-4 
line number parameter - 
JN 4-17 
line numbers 
in object code 4-10, 4-16 
in source code 4-17 
LINK 3-8, 3-15, 3-23 
LINK command prompts 3-8, 
3-15, 3-23 
linked list 1-4 
Linker 3-16 
libraries 3-9, 3-16, 3-23 
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linking multiple modules 3-8, 
C-14 

$LIST 4-26, 5-11 

LIST file 3-9, 3-15, 3-23 


list file prompt 3-9, 3-15, 3-23 


listing, compiler sample 4-26 
LEIST<3-11 
LOAD 5-11 
local variable C-9 
logical operators 8-7 
true-false table 8-7 
long string parameter - 
/S 4-18 
looking for a record, 
ISAM D-6 
loop control variables 5-14 
low resolution 6-26 
LPT1 A-16 
LPT2 A-16 
LPT3 A-16 
.LST extension 4-6 


M 


main module, definition of C-2 


main program, definition 
of C-1 
manual 
general information iii 
how to use iil 
math output, formatting 7-12 
maximum program size 3-7, 
3-13, 3-21, 4-23 
maximum size of data 
segment ix 
maximum size of string 
space ix 
medium resolution 6-26 
memory information A-7 
memory map A-8 
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MERGE 5-11 
metacommands 5-22 
minimum record 
allocation D-19 
mismatched arguments C-8 
MOD 8-5 
modular programming C-1 
$MODULE 
metacommand C-18 
advantages of C-13 
chaining files C-17 
common errors C-8 
global variable C-10 
scope of variables C-9 
shared variable C-10 
Static variables C-11 
subprogram libraries C-14 
using COMMON 
blocks C-12 
module, description of C-1 
modules, linking multiple 3-8, 
C-14 
modulo arithmetic 8-5 
multimodule application, 
definition of C-1 
multiple modules, linking 3-8, 
C-14 
multiple statements on a 
line 5-6 
multiplication 8-4 


N 


/N parameter 4-17 
named COMMON 
blocks C-12 
naming files 6-4, 6-5 
negation 8-4 
NEW 5-11 
new file ISAM, building D-87 


Next Word 5-18 /E parameter 4-10 


nonexecutable statements 5-5 /X parameter 4-11 
nonkey fields, ISAM D-19 ON KEY(n) 5-11 
nonrecoverable errors, library ON PEN 5-11 
manager E-8 ON PLAY 5-11 
nonsegmented record, ON STRIG(n) 5-11 
ISAM D-4 ON TIMER 5-11 
NOT 8-8 one-module structure, 
NUL 4-6 library C-14 
number of files 5-19 OPEN (file) 6-14, 6-17 
number, file 6-3 OPEN “COM... B-6 
numeric characters 5-6 open modes, ISAM 
numeric comparisons 8-6 See ISAM Open Modes 
numeric constants 7-3 opening a communications 
numeric expressions 8-3 file B-1 
numeric functions 8-11 opening a file, ISAM D-6 
numeric variables 7-5, 7-7 opening files 6-3 
opening modes ISAM, 
file D-58 
operational differences 5-11 
O operations, ISAM D-7 
operators 
Y arithmetic 8-4 
concatenation 8-14 
/O parameter 4-18 functions 8-11, 8-15 


.OBJ extension 1-6, 4-5 


OBJ filename extension 3-8, logical 8-7 


numeric 8-3 


3-15, 3-23 
lational 8-6 
object code listing 4-14 are acta 
object code parameter - optimization, definition of 1-6 
/ — optimizing compiler 1-6 
object file 1-5, 4-5 OR 8-8 
object filename compiler or. exclusive 8-8 
oo a order of execution 8-12 
object modules prompt 3-8, output file mode 6-14 
3-15, 3-23 output files 
S$OCODE 4-26 compiler 1-6 
octal 7-5 output signals I/O, control 
Offset column on compiler ne Tk 
listing 4-26 output variable C-5 
old library parameter - output, formatting 7-12 


/O 4-18 overflow 4-16, 5-15 
ON COM(n) 5-11 overscan 6-22 


ON ERROR 4-10, 5-12 
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P 


package, contents of 2-3 
pagesize E-2 
palette 6-27 
parameter addressability C-27 
parameters ISAM, key 
field D-20 
parameters, compiler 4-9 
See also compiler 
parameters 
parameters, formal C-29 
parameters, passing by 
reference C-29 
parameters, passing by 
value C-29 
parentheses 8-12 
passing argument expressions, 
assembly language 
interface C-29 
passing array arguments C-7 
passing arrays, assembly 
language interface C-30 
passing by reference C-5 
passing by value C-5, C-7 
passing parameters with 
CALL C-5 
argument C-5 
common errors C-8 
expressions C-8 
formal parameter C-5 
input variable C-5 
output variable C-5 
passing by reference C-5, 
C-6 
passing by value C-7 
passing parms by 
reference C-29 
passing strings, assembly 
language interface C-31 
path 6-5, 6-6 
paths 6-11 
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PEEK 5-19 
PEN STOP 5-11 
pixel 6-25 
PLAY(n) 5-11 
pointer D-12, D-20, D 
D-25, D-26, D-27, D- 
D-31, D-48, D-52, D- 
D-65 
POKE 5-19 
portability, program iv 
precedence 8-12 
precision 7-7 
prerequisites for using book iii 
Previous Word 5-18 
Print switch (/p), 
REBUILD D-85 
products, related viii 
program editor 5-17 
program portability iv 
programming, modular C-1 
publication changes xiv 
publications, related viii 
PUT (files) 6-18 


-24, 
29, 
5 


9 
4, 


R 


/R parameter 4-18 
random files 6-16 
REBUILD utility 
See ISAM REBUILD utility 
REBUILD utility 
statements D-97 
FIELD D-98 
KEYED BY D-100 
RECORD D-97 
SPLIT KEYSET D-101 
rebuilding a file D-12 
record description, 
ISAM D-18 
record pointer, ISAM D-12 


RECORD Statement D-97 
RECORD statement, 
REBUILD utility D-97 
record types, ISAM D-4 
record, BASIC data D-13 
recoverable errors, library 
manager E-11 
redirecting output, 
REBUILD D-90 
related books viii 
related products viii 
relational operators 8-6 
relative form for specifying 
coordinates 6-29 
remarks 5-6 
RENUM 5-11 
replacing a damaged file D-87 
reserved words 5-8, 7-6 
list of 5-8 
resolution 6-26 
response file, library 
manager E-6 
RESUME 4-10, 5-12 
/E parameter 4-10 
/X parameter 4-11 
RETURN 4-16 
returning to caller, assembly 
language interface C-28 
root directory 6-11 
rounding 4-14, 7-10 
run file 3-9, 3-15, 3-23 
run file prompt 3-9, 3-15, 3-23 
running a program 3-10, 3-18, 
3-25 
running out of disk space D-88 
runtime module 1-8, 4-19 


S 


/S parameter 4-18 
sample compiler listing 4-26 
SAMPLE1.BAT 3-26 
SAVE 5-11 
saved file position, 

locating D-64 
scalar variables A-11 
scanning parameter - /4 4-12 
scope of variables C-9 
screen 6-21 

use of 6-20 
screen displays 6-20 
scrolling 6-22 
search order for adapters A-16 
security, source code 1-6 
seek modes, ISAM 
See ISAM Seek Modes 

seeking a record, ISAM D-6 
segment, maximum size of 

data ix 
segmented record, ISAM D-4 
segmented records, 

ISAM D-16 
semicolon on command 

line 4-7 
sequential access method D-1 
sequential files 6-14 
shared variable C-10 
short error-message 

module 2-3 
simple variables, passing C-6 
single-key description, 

REBUILD D-84 
Single-key switch (/s), 

REBUILD D-86 
single-precision 7-7 
size of line 5-21 
sizes, data types D-73 
SMALLERR.OBJ 2-3 
soft key display 6-22 
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software changes ix 
See also summary of 
changes 
software support 1x 
source code security 1-6 
source file 1-6 
source file, REBUILD D-83 
source filename compiler 
prompt 4-4 
Source Line on compiler 
listing 4-26 
source listing 4-5 
spaces 5-8 
SPC 4-14 
special characters 5-7 
special code parameters 4-14 
specification of files 6-5 
specifying coordinates 6-29 
specifying filenames 
See filename 
speed of execution 1-6, 3-11 
split key file, ISAM D-3 
split keys D-16 
split keys, use of D-30 
SPLIT KEYSET 
Statement D-101 
SPLIT KEYSET statement, 
REBUILD utility D-101 
stack diagram C-26 
stack segment requirements, 
assembly language 
interface C-25 
starting 
compiler 4-4 
statements not 
implemented 5-11 
statements, REBUILD utility 
See REBUILD utility 
statements 
Static arrays 7-17 
Static variable C-11 
status code, assembler 
interface D-75 
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status indicators, ISAM 
See ISAM Status Indicators 
STEP 6-29 
storage devices 6-8 
STRIG(n) 5-11 
string comparisons 8-7 
string constants 7-13 
string descriptor 5-20, A-12 
string expressions 8-14 
String functions 8-15 
string length 5-20 
string parameter - /S 4-18 
String space 5-20 
string space, maximum size 
of ix 
string variable ISAM, use 
of D-27 
string variables 7-14 
strings ISAM, variable 
length D-4 
strings, passing C-31 
structuring assembly language 
programs C-21 
structuring modular 
programs C-13 
structuring subprogram 
libraries C-14 
subdirectories 6-11 
subprogram C-2 
calling C-3 
illustration C-3 
intramodule call C-3 
restrictions on calling C-3 
subprograms, calling assembly 
language C-19 
subroutines, ISAM 
See ISAM Subroutines 
$SUBTITLE 4-26 
subtraction 8-4 
summary of changes ix 
expanded DOS access x 
graphics support x 
new functions xiii 


new metacommands xii 
new statements xiii 
program control ix 
support, device 6-9 
support, software ix 
switches, REBUILD D-85 
Force (/f) D-86 
Print (/p) D-85 
Single-key (/s) D-86 
Terse (/t) D-86 
syntax of command line 
compiler 4-6 
syntax REBUILD, 
data-dictionary 
language D-96 
system components, 
requirements vi 
system failure, 
consequences D-87 


T 


/T parameter 4-13 
TAB 4-14 
target file, REBUILD D-84 
techniques, formatting 
output 7-12 
termination codes, 
compiler 3-26, 4-24 
Terse switch (/t), 
REBUILD D-86 
text mode 6-21 
$TITLE 4-26 
transcendental functions 5-14 
translation 1-3 
tree-structured 
directories 6-12 
trees, ISAM D-3 
TRON and TROFF 4-16, 5-12 
true 8-6, 8-8 


true-false table 8-7 

truncation 4-14 

twos complement 8-10, 8-11 

type-declaration 

characters 7-8, 7-15 

types of directories 6-11 
root directory 6-11 
subdirectories 6-11 


U 


unrecoverable damaged file, 
ISAM D-88 

update, software ix 

See also summary of 
changes 

USER 6-8 

using book, prerequisites ili 

using ISAM files D-1 

using the compiler 2-4, 4-3 
first time 2-4 


V 


/V parameter 4-11 
variable C-5 
input C-5 
output C-5 
shared C-10 
variable list 1-4 
variable-field record, 
ISAM D-4 
variable-length strings, 
ISAM D-4 
variable, global C-10 
variable, local C-9 
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variable, static C-11 writing an ISAM 
variables 7-5, 7-6, 7-15, A-11 application D-4 

declaring types 7-6 

naming 7-6 

storage of A-11 

type-declaration X 

characters 7-15 

types of 7-5 “A 

variables, aliasing C-8 


variables, scope of C-9 /X parameter 4-11 


variables, string 7-14 XOR 8-8 
visual page 
See display pages 
Numerals 


Ww 


/4 parameter 4-12 
80-column display vii 


/W parameter 4-12 
world coordinates 6-30 
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Continued from inside front cover 


SOME STATES DO NOT ALLOW THE 
EXCLUSION OF IMPLIED 
WARRANTIES, SO THE ABOVE 
EXCLUSION MAY NOT APPLY TO 
YOU. THIS WARRANTY GIVES YOU 
SPECIFIC LEGAL RIGHTS AND YOU 
MAY ALSO HAVE OTHER RIGHTS 
WHICH VARY FROM STATE TO 
STATE. 


IBM does not warrant that the functions 
contained in the program will meet your 
requirements or that the operation of the 
program will be uninterrupted or error 
free. 


However, IBM warrants the diskette(s) or 
cassette(s) on which the program is fur- 
nished, to be free from defects in materials 
and workmanship under normal use for a 
period of ninety (90) days from the date of 
delivery to you as evidenced by a copy of 
your receipt. 


LIMITATIONS OF REMEDIES 


IBM’s entire liability and your exclusive 
remedy shall be: 


1. the replacement of any diskette(s) or 
cassette(s) not meeting IBM’s “Limited 
Warranty” and which is returned to IBM 
or an authorized IBM PERSONAL 
COMPUTER dealer with a copy of your 
receipt, or 


2. if IBM or the dealer is unable to deliver a 
replacement diskette(s) or cassette(s) 
which is free of defects in materials or 
workmanship, you may terminate this 
Agreement by returning the program 
and your money will be refunded. 


IN NO EVENT WILL IBM BE LIABLE 
TO YOU FOR ANY DAMAGES, 
INCLUDING ANY LOST PROFITS, 
LOST SAVINGS OR OTHER 
INCIDENTAL OR CONSEQUENTIAL 


DAMAGES ARISING OUT OF THE 
USE OR INABILITY TO USE SUCH 
PROGRAM EVEN IF IBM OR AN 
AUTHORIZED IBM PERSONAL 
COMPUTER DEALER HAS BEEN 
ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGES, OR FOR ANY 
CLAIM BY ANY OTHER PARTY. 


SOME STATES DO NOT ALLOW THE 
LIMITATION OR EXCLUSION OF 
LIABILITY FOR INCIDENTAL OR 
CONSEQUENTIAL DAMAGES SO 
THE ABOVE LIMITATION OR 
EXCLUSION MAY NOT APPLY TO 
YOU. 


GENERAL 


You may not sublicense, assign or 
transfer the license or the program 
except as expressly provided in this 
Agreement. Any attempt otherwise to 
sublicense, assign or transfer any of the 
rights, duties or obligations hereunder is 
void. 


This Agreement will be governed by the 
laws of the State of Florida. 


Should you have any questions 
concerning this Agreement, you may 
contact IBM by writing to IBM Personal 
Computer, Sales and Service, P.O. Box 
1328-W, Boca Raton, Florida 33432. 


YOU ACKNOWLEDGE THAT YOU 
HAVE READ THIS AGREEMENT, 
UNDERSTAND IT AND AGREE TO 
BE BOUND BY ITS TERMS AND 
CONDITIONS. YOU FURTHER 
AGREE THAT IT IS THE COMPLETE 
AND EXCLUSIVE STATEMENT OF 
THE AGREEMENT BETWEEN US 
WHICH SUPERSEDES ANY 
PROPOSAL OR PRIOR AGREEMENT, 
ORAL OR WRITTEN, AND ANY 
OTHER COMMUNICATIONS 
BETWEEN US RELATING TO THE 
SUBJECT MATTER OF THIS 
AGREEMENT. 


© IBM Corp. 1985 
All rights reserved. 


International Business 
Machines Corporation 
P.O. Box 1328-S 

Boca Raton, Florida 33432 


Printed in the 
United States of America 


6138587 


